home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / tex / ptf12.zip / PTFDOCS.SRC < prev    next >
Text File  |  1990-05-14  |  163KB  |  5,926 lines
  1. --::::::::::
  2. --ptfsum.ptf
  3. --::::::::::
  4. .comment
  5. .! Software User's Manual (2167A, DI-MCCR-80019A) for:
  6. .!   PORTABLE TEXT FORMATTER (PTF)
  7. .! Prepared by: Richard Conn
  8. .! Date:        2/27/90
  9. .! Modifications
  10. .! 08/18/89  1.0  Rick Conn  Initial Version
  11. .! 02/27/90  1.1  Rick Conn  PTFPCR-1 to PTFPCR-4 Fixes
  12. .! 05/07/90  1.2  Rick Conn  PTFPCR-5 and PTFPCR-6 Fixes
  13. .!
  14. .! Description and Purpose:
  15. .!   1. The Software User's Manual (SUM) provides user personnel
  16. .! with instructions sufficient to execute one or more related
  17. .! Computer Software Configuration Items (CSCIs).
  18. .!   2. The SUM provides the steps for executing the software, the
  19. .! expected output, and the measures to be taken if error messages
  20. .! appear.
  21. .!   3. The information required by this DID (Data Item Descriptor)
  22. .! is directed to the functional user of the CSCI(s), as opposed
  23. .! to the operator of the computer system.  If this distinction does
  24. .! not exist, the user will need to refer to both the Computer
  25. .! System Operator's Manual and the SUM to operate the computer system
  26. .! and to use the CSCI(s).
  27. .!
  28. .! Tailoring Instructions:
  29. .!    To tailor this template, fill in the areas surrounded by
  30. .! [] as indicated.
  31. .comment
  32.  
  33. .comment
  34. .! This is set for PICA type (10 chars/inch).  Change accordingly
  35. .! for ELITE or other type styles.  Also, the default top and bottom
  36. .! margins and headers are used, giving 1 inch top and bottom for
  37. .! both margins and headers at 6 lines/inch.  No auto-paragraphing.
  38. .comment
  39. .lm 11
  40. .rm 70
  41.  
  42. .comment
  43. .! The following reads in a set of macros used by all the 2167A
  44. .! document templates.
  45. .comment
  46. .include zzz2167a.ptf
  47.  
  48. .comment
  49. .! Various constants
  50. .comment
  51. .! Set the index line length to 2 less than 1/2 the total line length
  52. .indexlength 28
  53. .! Set underline mode to not underline punctuation characters
  54. .ulmode nopunct
  55. .! Name of the index file
  56. .vs INDEXFILE ptf.idx
  57. .vs PTFIDXFILE ptfidx.ptf
  58. .vs ERRORFILE ptf.err
  59.  
  60. .comment --------------- MACROs -------------------
  61. .! The following macros are defined:
  62. .!
  63. .!   FIG title   -- generate a figure title and place it in the
  64. .!                  table of contents for figures
  65. .!   EFIG        -- end a figure with a dashed line (optional)
  66. .!   PRFIG       -- print the table of contents for figures
  67. .!
  68. .!   NOTE        -- begin a note
  69. .!   ENDNOTE     -- end a note
  70. .!
  71. .!   ICOMM text  -- enter command info into the index
  72. .!   COMM  text  -- enter command info into the TOC
  73. .!
  74. .!   list  n     -- start a list with an indent of n
  75. .!   item  token -- make a new list element using the token
  76. .!   nolist      -- end the current list
  77. .!
  78. .comment --------------- MACROs -------------------
  79. .nr f 0
  80. .! ------------------- MACRO ---------------------
  81. .define FIG
  82. .nr f +1
  83. .contsel 1
  84. .cl 0 Figure @nf: @1 @2 @3 @4 @5 @6 @7 @8 @9
  85. .ce on
  86. Figure @nf
  87. .br
  88. .ul
  89. @1 @2 @3 @4 @5 @6 @7 @8 @9
  90. .ce off
  91. .sp
  92. .contsel
  93. .en
  94. .! ------------------- MACRO ---------------------
  95. .define EFIG
  96. .br
  97. .ce
  98. ------------------------------------------------
  99. .sp
  100. .en
  101. .! ------------------- MACRO ---------------------
  102. .define PRFIG
  103. .contsel 1
  104. .pc
  105. .contsel
  106. .en
  107. .! ------------------- MACRO ---------------------
  108. .define OPT
  109. .br
  110. .need 5
  111. .sp
  112. .ti -5
  113. @1 @2 @3 @4 @5 @6 @7 @8 @9
  114. .br
  115. .en
  116. .! ------------------- MACRO ---------------------
  117. .define NOTE
  118. .sp
  119. .ce
  120. NOTE
  121. .sp
  122. .fi
  123. .li +5
  124. .ri +5
  125. .en
  126. .! ------------------- MACRO ---------------------
  127. .define ENDNOTE
  128. .sp
  129. .nf
  130. .li -5
  131. .ri -5
  132. .en
  133. .! ------------------- MACRO ---------------------
  134. .define ICOMM
  135. \index command, @1 @2 @3 @4 @5 @6 @7 @8 @9
  136. \index @1 @2 @3 @4 @5 @6 @7 @8 @9
  137. .en
  138. .! ------------------- MACRO ---------------------
  139. .define COMM
  140. \cl 3 @1 @2 @3 @4 @5 @6 @7 @8 @9
  141. \sp
  142. \need 5
  143. \ti -5
  144. @1 @2 @3 @4 @5 @6 @7 @8 @9
  145. \sp
  146. .en
  147. .! ------------------- MACRO ---------------------
  148. .define list
  149. .nr a @1
  150. .li +@1
  151. .li +@1
  152. .ri +@1
  153. .en
  154. .! ------------------- MACRO ---------------------
  155. .define item
  156. .sp
  157. .ti -@na
  158. @1
  159. .en
  160. .! ------------------- MACRO ---------------------
  161. .define nolist
  162. .li -@na
  163. .li -@na
  164. .ri -@na
  165. .sp
  166. .en
  167. .comment ------------------ END OF MACROs ----------------------
  168.  
  169. .comment
  170. .! Set the page heading to contain the Document Control
  171. .! Number and date.  The Document Control Number contains
  172. .! revision and volume identification as applicable.
  173. .! PTF 1.2 Software User's Manual
  174. .comment
  175. .he //PTF 1.2 Software User's Manual//
  176.  
  177. .ce on
  178.  
  179. .comment
  180. .! The next line contains the revision indicator and the
  181. .! date of revision.
  182. .comment
  183.  
  184. Version 1.2: 7 May 1990
  185.  
  186. .spaceto +15
  187. SOFTWARE USER'S MANUAL
  188. .sp
  189. FOR THE
  190. .sp
  191. .comment
  192. .! The name of the system appears here
  193. .comment
  194. PORTABLE TEXT FORMATTER (PTF)
  195.  
  196. .spaceto -20
  197. .comment
  198. .! The contract number and other information appear here
  199. .comment
  200. CONTRACT NO. <None>
  201. .sp
  202. CDRL SEQUENCE NO. <None>
  203. .sp 2
  204. Prepared for:
  205. .sp
  206. Ada Software Repository
  207. Host Computer WSMR-SIMTEL20.ARMY.MIL
  208. White Sands Missile Range, New Mexico
  209. .sp 2
  210. Prepared by:
  211. .sp
  212. Richard Conn
  213.  
  214. .ce off
  215.  
  216. .comment
  217. .! The next page starts with the Scope and is numbered 1.
  218. .! The table of contents is created at the end of the PTF
  219. .! output file and should be inserted after this title page.
  220. .comment
  221. .bp 1
  222. .fo //#//
  223. .cl
  224. .SECT 0 1 Scope
  225. .SECT 1 1.1 Identification
  226. .PP
  227. This manual is the Software User's Manual for the
  228. .ul
  229. Portable Text Formatter
  230. (PTF), Version 1.2.  This manual applies to the PTF as it operates
  231. on any hardware platform onto which PTF has been properly installed.
  232. .index PTF
  233. .SECT 1 1.2 System overview
  234. .include ptfover.ptf
  235. .SECT 1 1.3 Document overview
  236. .PP
  237. The purpose of this manual is to instruct the user in how to prepare
  238. files for input to PTF and execute PTF.  This manual is also designed
  239. as a reference document in compliance with
  240. DoD-STD-2167A, DI-MCCR-80019A (Software User's Manual).
  241. .index DoD-STD-2167A
  242. .index DI-MCCR-80019A
  243. .index Software User's Manual
  244. .PP
  245. Sections 3 and 4 and Appendix A contain the key parts of this document.
  246. Section 3 is a detailed explanation of the commands recognized by PTF.
  247. It contains a complete listing of these commands, grouped by category,
  248. with an explanation and examples of their use.  Section 4 contains
  249. a complete listing of all error messages and warning messages which
  250. may be produced by the PTF and PTFIDX programs.  These messages flag
  251. errors which the user may correct, internal errors which a programmer
  252. will have to correct, and warnings which the user may wish to correct.
  253. Appendix A contains a summary of the commands explained in Section 3.
  254. This is a complete summary, grouped by category.
  255. .bp
  256. .cl
  257. .SECT 0 2 Referenced documents
  258. .PP
  259. Mark Stuart Brader,
  260. .ul
  261. An Incremental Text Formatter,
  262. Department of Computer Science, University of Waterloo, CS-81-12.
  263. .PP
  264. Department of Defense,
  265. .ul
  266. Proposed MIL-HDBK-1804: Military Handbook Ada Style Guide,
  267. April 30, 1988.  This document as followed closely while preparing the
  268. source code of PTF.  It is available in the Ada Software Repository.
  269. .index MIL-HDBK-1804
  270. .PP
  271. R. Furuta, J. Scofield, and A. Shaw,
  272. .ul
  273. Document Formatting Systems: Survey, Concepts, and Issues,
  274. ACM Computing Surveys, September 1982, Pp. 417.
  275. .PP
  276. Brian W. Kernighan and P.J. Plauger,
  277. .ul
  278. Software Tools,
  279. Addison-Wesley (1976).  PROFF was produced by rewriting the formatter
  280. named FORMAT described in this book and by incorporating ideas from
  281. the Freshwater Institute RUNOFF, NROFF, University of Waterloo SCRIPT,
  282. and other formatters of similar nature.
  283. .PP
  284. Allyn M. Shell,
  285. .ul
  286. NASA/GSFC Standard Ada Pretty Printer, Version 1.1,
  287. May 1988.  This tool was used to format the Ada source code which comprises
  288. PTF.  This pretty printer and its documentation are available in the
  289. Ada Software Repository.
  290. .PP
  291. Ozan S. Yigit and Steven Tress,
  292. .ul
  293. PROFF User's Guide Version 1.0,
  294. March 1984, SIMTEL20 archives.  This document acted as a statement
  295. of requirements for PTF and also was lifted in many parts for literal
  296. incorporation into this Software User's Manual.
  297. .bp
  298. .cl
  299. .SECT 0 3 Execution procedures
  300. .ap
  301. .fi
  302. .ju
  303. .cl
  304. .SECT 1 3.1 General Description
  305. .SECT 2 3.1.1 The Input
  306.  The text that is to be formatted by PTF is typed into an input file
  307. using any text editor. This file contains the text to be formatted
  308. as well as PTF commands.
  309. .index command lines
  310. .index text lines
  311.  Each line in the input file is either a command line or a text line. A
  312. command line is a line that begins with a period ("."). All other lines are
  313. text lines. The command lines are not printed - they tell PTF how you want
  314. it to format the text that follows. Appendix A summarizes all of the PTF
  315. commands for a quick reference.
  316. .SECT 3 3.1.1.1 Text
  317.  Text can be entered into the input file in any format. PTF removes all extra
  318. blanks and tabs between words when operating in fill mode. This means you do
  319. not have to worry about how many words you put on a line, and you can break 
  320. lines wherever it is convenient to your typing. Note, however, that you cannot
  321. break a word between two lines.
  322. .index auto-paragraphing mode
  323.  Blanks and tabs at the beginning of a line signal to begin a new
  324. paragraph if PTF is in auto-paragraphing mode.  Otherwise, blanks and
  325. tabs at the beginning of a line are ignored unless PTF is in nofill mode,
  326. in which case tabs are converted into the appropriate number of spaces.
  327. .SECT 3 3.1.1.2 Commands
  328. .index command lines
  329.  A command is a line that starts with a period. Immediately following the
  330. period is a command name. Commands
  331. are case-sensitive, so the commands ".list", ".List", and ".LIST" are three
  332. different commands. Some commands accept a numeric quantity or a
  333. character string parameter, which must be separated from the command name
  334. by a space. For example, a left
  335. indent command might appear as follows:
  336. .save
  337. .li +5
  338. .nf
  339. .sp
  340. .need 5
  341. |
  342. |It is to do nothing that the elect exists.
  343. |.li 5
  344. |- Oscar Wilde
  345. |
  346. .restore
  347.  Assuming that the left margin was at column 1, PTF would produce the
  348. following:
  349. .save
  350. .li +5
  351. .nf
  352. .sp
  353. .need 4
  354. |
  355. |It is to do nothing that the elect exists.
  356. |     - Oscar Wilde
  357. |
  358. .fi
  359. .restore
  360. .sp
  361. In the examples above, as in those following, the vertical line indicates
  362. the left edge of input or the left edge of the printed page.
  363. .index numeric arguments
  364. .index command lines, arguments
  365.  The number following the command may be prefixed by a "+" or "-" sign.
  366. This plus or minus sign indicates an addition or subtraction of the number
  367. to or from the current value for the command. For example, the text:
  368. .sp
  369. .save
  370. .li +5
  371. .nf
  372. .need 11
  373. |
  374. |Nothing to do but work,
  375. |.li +3
  376. |Nothing to eat but food,
  377. |.li -3
  378. |Nothing to wear but clothes
  379. |.li +3
  380. |To keep one from going nude.
  381. |.li +7
  382. |-Benjamin King
  383. |
  384. .li -5
  385. .sp
  386. will produce as output:
  387. .sp
  388. .li +5
  389. .need 7
  390. |
  391. |Nothing to do but work,
  392. |   Nothing to eat but food,
  393. |Nothing to wear but clothes
  394. |   To keep one from going nude.
  395. |          -Benjamin King
  396. |
  397. .restore
  398.  If a number is not supplied with a command that requires a number, PTF
  399. will usually employ
  400. a default value. The defaults for each command are summarized in
  401. Appendix A.
  402. .SECT 2 3.1.2 The Output
  403.  The main functions performed by PTF are 
  404. .ul
  405. filling
  406. and 
  407. .ul
  408. justifying.
  409. .index fill mode
  410. .index justify mode
  411. A line is
  412. filled by packing as many words onto it as will fit. The line is justified
  413. by spacing words evenly between the left and right margins. When PTF starts,
  414. it assumes that the text is to be filled and justified. Of course, when fill
  415. and justify are not needed (as in the case of a letter or a table), there are
  416. commands to turn these features off, and back on again, as necessary.
  417.  When PTF is in fill mode, it normally removes extra spaces and tabs.
  418.  Many PTF commands cause a
  419. .ul
  420. break
  421. .index break
  422. to occur in the output. This means that the line currently being filled is 
  423. immediately output without justification.
  424. Any following text goes into a new output line.
  425. .SECT 2 3.1.3 Executing PTF
  426. .index executing PTF
  427. .index PTF, executing
  428.  Once a text file is ready for formatting, PTF is started by typing
  429. the program name, various options, name of one or more input files
  430. and the name
  431. of the output file. For example the command
  432. .sp
  433. .li +5
  434. ptf -po5 ptfman.ptf ptf.man
  435. .sp
  436. .li -5
  437. would produce a document named "ptf.man" from an input file "ptfman.ptf." 
  438. Each line would be shifted right by 5 spaces (the "-po5" option).
  439. See section 3.3 for details on how to execute the PTF program.
  440. .cl
  441. .SECT 1 3.2 Command Descriptions
  442.  This section describes PTF commands. Commands specify how the program is
  443. to process the text lines in the input file. Lines in the input file that
  444. begin with a period (or the control character selected by the user) 
  445. immediately followed by a command name are commands. Any line that begins
  446. with a period and followed by a _#, a _.,
  447. or a _! is a comment line and is ignored
  448. .index comment
  449. .index command, comment
  450. by PTF - this allows you to put information in the file that will be neither
  451. processed nor output by PTF.
  452. .index parameters
  453. .index command, parameters
  454.  As described earlier, some of the commands can be followed by "parameters."
  455. Parameters are used in executing a command; for example, in the command
  456. ".sp 3", the parameter "3" tells the formatter to insert 3 blank lines into
  457. the document. The following conventions are used in describing the parameters:
  458. .sp
  459. .li +5
  460. .ri +5
  461. .ti -3
  462. o Parameters surrounded by square brackets are optional. If not supplied, PTF
  463. assumes a default value 
  464. (e.g., .sp [n]).
  465. .sp
  466. .ti -3
  467. o Parameters surrounded by angle brackets are mandatory. PTF will display
  468. a fatal error message if the parameter is absent (e.g., .set <variable name>).
  469. .sp
  470. .ti -3
  471. o A bar character separating the parameters within brackets indicates an
  472. alternative (e.g., .st [+|-][n] means both .st [+n] and .st [-n]).
  473. .li -5
  474. .ri -5
  475.  In describing the commands, the command is typed exactly as accepted by PTF
  476. with the associated control character default ("."). If more than one form of
  477. the command is accepted by PTF, the command names are separated with a
  478. bar indicating an alternative.
  479. .SECT 2 3.2.1 Filling and Justifying
  480. .nap
  481. .li +5
  482. .!
  483. .! Change the control character from period (".") to a backslash ("\")
  484. .! to avoid the interpretation of the command headers.
  485. .!
  486. .cchar \
  487. \!
  488. \! Variable creation
  489. \! We use variables to avoid re-typing of multiple options over
  490. \! and over again. These variable names will be reused in the
  491. \! appendix to produce a quick reference
  492. \!
  493. \set FILL .fi | .f | .fill
  494. \COMM @FILL
  495. \ICOMM fill
  496. The fill command causes a line to be filled with as many words as the right
  497. margin minus the right
  498. indent allows. For this purpose, all extra blanks and tabs are removed
  499. between
  500. words. Each word is separated with a single blank. PTF automatically assumes
  501. fill mode during the startup.
  502. \set NOFILL .nf | .nofill
  503. \COMM @NOFILL
  504. \ICOMM no fill
  505. No fill discontinues the filling of the text. PTF simply copies the text
  506. to the output. This command may be used to pass tables and other text
  507. unaltered through the formatter.
  508. \set JUST .ju | .j | .justify
  509. \COMM @JUST
  510. \ICOMM justify
  511. Justify causes the words on a line to be evenly spaced between the left and
  512. the right margins
  513. (plus the left and minus the
  514. right indent). Note that lines can be justified only if lines are also
  515. being filled. PTF automatically assumes justify mode during the startup.
  516. \set NOJUST .nj | .nojustify
  517. \COMM @NOJUST
  518. \ICOMM no justify
  519. No justify discontinues the justification of text.
  520. \li -5
  521. \cchar
  522. .SECT 2 3.2.2 Text Formatting
  523. .li +5
  524. .cchar \
  525. \set BREAK .br | .break
  526. \COMM @BREAK
  527. \ICOMM break
  528. Break causes a break: the current line is printed without justification,
  529. and the next word is placed at the beginning of a new line. Note that many
  530. PTF commands cause an implicit break.
  531. \set TINDENT .ti | .i | .left [+|-][n]
  532. \COMM @TINDENT
  533. \ICOMM temporary indent
  534. Temporary indent is identical to the left indent command except that it 
  535. applies only to the next line of printed text. Thus, the command
  536. ".ti +5" would cause the next line to be printed 5 spaces to the right
  537. of those that follow.
  538. \set SPACETO .st | .spaceto [-][n]
  539. \COMM @SPACETO
  540. \ICOMM space to
  541. Spaceto allows spacing to line [n] from the top of the current page.
  542. If a negative [n] is specified, then spacing is performed to line [n]
  543. from the bottom of the page. The top margin and header lines and bottom
  544. margin and footer lines are not counted (so ".st 0" places you at the
  545. first line on the page). Thus, footnotes
  546. can be set at a fixed distance from the bottom of the page by a command such
  547. as ".st -5".
  548. \set SPACE .sp | .s | .skip [n]
  549. \COMM @SPACE
  550. \ICOMM space
  551. Skip causes a break and skips [n] lines. The skip command
  552. is dependent on the setting of line spacing.
  553. \set CENTER .ce | .center [n | on | off]
  554. \COMM @CENTER
  555. \ICOMM center
  556. Center causes the next [n] lines of text to be centered between the left
  557. and right margins and left and right
  558. indents.
  559. If [n] is omitted, only the next line is centered.
  560. Centering may be started with "on" and terminated with
  561. "off", in which case all input lines between these commands will be centered.
  562. \set UNDLINE .ul | .underline [n | on | off]
  563. \COMM @UNDLINE
  564. \ICOMM underline
  565. Underline causes the text on the next [n] input lines to be underlined
  566. when printed. If [n] is omitted, only the next line is underlined.
  567. This command
  568. does not cause a break, so words in filled text may be underlined by:
  569. \sp
  570. \save
  571. \cchar
  572. .li +5
  573. .nf
  574. .need 11
  575. .FIG Example of Underlining
  576. .sp
  577. |
  578. |The "Pay-off" Theory: Only
  579. |.ul
  580. |losers
  581. |believe in luck, horses, horoscopes
  582. |and
  583. |.ul
  584. |lotteries.
  585. |
  586. .li -5
  587. .sp
  588. to get
  589. .li +5
  590. .sp
  591. .ne 4
  592. .fi
  593. |
  594. .br
  595. |The "Pay-off" Theory: Only
  596. .ul
  597. losers
  598. believe in
  599. .br
  600. |luck, horses, horoscopes and
  601. .ul
  602. lotteries.
  603. .br
  604. |
  605. .sp 2
  606. .restore
  607. Underlining may be started with "on" and terminated with "off," similar to
  608. the centering command.
  609. \set DU .du
  610. \COMM @DU
  611. \ICOMM disable underline
  612. Turns underlining off. All underlining commands are ignored. This feature is
  613. useful for rough drafts.
  614. \set EU .eu
  615. \COMM @EU
  616. \ICOMM enable underline
  617. Turns the underlining feature back on. Underlining is enabled during the PTF
  618. startup.
  619. \set CUNDLINE .ulmode [all | nopunct]
  620. \COMM @CUNDLINE
  621. \ICOMM underline mode
  622. Underline mode sets the form of underlining to cover all characters of
  623. a word or to not underline the punctuation characters.  The punctuation
  624. characters are shown below.
  625. \sp
  626. \cchar
  627. .ne 8
  628. .FIG Punctuation Characters
  629. .nf
  630. .nap
  631.         _.  (Period)       _?  (Question Mark)
  632.         _,  (Comma)        _!  (Exclamation Mark)
  633.         _;  (Semicolon)
  634. .ap
  635. .fi
  636. .sp 2
  637. .cchar \
  638. \set BOLD .bd | .bold [n | on | off]
  639. \COMM @BOLD
  640. \ICOMM bold
  641. The bold command causes the text on the next [n] input lines to be highlighted
  642. by overstriking. If [n] is omitted, only the next line is highlighted.
  643. Bolding may be started with "on" and terminated with "off" as in the
  644. case of the center and underline commands.
  645. \set DBO .db | .dbo
  646. \COMM @DBO
  647. \ICOMM disable bolding
  648. Turns the bolding off. All bolding commands are ignored. This feature is
  649. useful for rough drafts.
  650. \set EBO .eb | .ebo
  651. \COMM @EBO
  652. \ICOMM enable bolding
  653. Turns the bolding feature back on. Bolding is turned on during the PTF
  654. startup.
  655. \li -5
  656. \cchar
  657. .SECT 2 3.2.3 Page Formatting
  658. .li +5
  659. .cchar \
  660. \set LS .ls | .spc | .spacing [n]
  661. \COMM @LS
  662. \ICOMM line spacing
  663. Line spacing is the command to set line spacing.
  664. Set n to 1 for single spacing,
  665. 2 for double spacing etc. If [n] is omitted, single spacing is enabled.
  666. \set BP .bp | .pg | .page [n]
  667. \COMM @BP
  668. \ICOMM begin page
  669. The begin page command causes a break, ends the current page, outputs
  670. footers if required and begins a new page,
  671. outputting headers if required. If [n] is present, the page number of
  672. the new page
  673. is set to [n]. The default action is to number the pages incrementally.
  674. \set PN .pn | .pagenumber [{lower__roman} | {upper__roman} | {arabic}] [text]
  675. \COMM @PN
  676. \ICOMM page number
  677. \index page number format
  678. The page number format
  679. command defines the format of the page number. Uppercase or lowercase Roman
  680. numerals may be obtained with "upper__roman"
  681. or "lower__roman" keywords. To convert the page numbers
  682. back to normal, "arabic" is specified. PTF uses Arabic numerals as
  683. a default.  PTF requires only the first letter ('a', 'l', or 'u') of
  684. the first token after the ".pn" to
  685. be specified, and the rest of the letters in the first argument are ignored.
  686. If either form of Roman numerals is selected, only numbers less than
  687. 1,000 can be printed; numbers equal to or larger than 1,000 are printed
  688. as 'zzz' or 'ZZZ' (depending on the case selected).
  689.  If the [text] option is also present, then [text] becomes the form of
  690. the page number as it is printed in the header, footer, contents, and
  691. index areas.  [text] should always contain a pound sign (#) character,
  692. for which the page number itself will be substituted.  If the [text]
  693. option is not present, the last setting (defaulted to just "#") is used.
  694. Examples:
  695. \sp
  696. \need 8
  697. \cc
  698. .FIG Sample Page Number Formats
  699. .cc \
  700. \sp
  701. \nf
  702. \na
  703. \ul
  704. Form of Command        Format of Page Number
  705. .pn arabic              1, 2, 3, etc. (assuming #)
  706. .pn arabic #            1, 2, 3, etc.
  707. .pn arabic A-#          A-1, A-2, etc.
  708. .pn lower__roman TOC-#   TOC-i, TOC-ii, TOC-iii, etc.
  709. .pn upper__roman #       I, II, III, etc.
  710. \fi
  711. \ap
  712. \sp
  713. \set NPA .np | .nopaging
  714. \COMM @NPA
  715. \ICOMM disable paging
  716. No paging disables the pagination. When PTF is in no paging mode,
  717. "begin page" (.bp) and "page length" (.pl) commands are ignored. This mode
  718. of operation is especially useful for using the PTF output with the
  719. multi-column formatter.
  720. \set PA .pa | .paging
  721. \COMM @PA
  722. \ICOMM enable paging
  723. Paging enables normal page generation. This command starts a 
  724. new page and restores the page length to the
  725. value previous to the ".np" command.
  726. \set NE .ne | .need | .tp | .testpage [n]
  727. \COMM @NE
  728. \ICOMM test page
  729. Test page checks to see whether at least [n] lines remain in the
  730. current page. If less than this number of lines remains, printing will resume
  731. at the top of a new page. If [n] is missing, it is assumed to be zero.
  732. \set HE .he | .header [n] <text>
  733. \COMM @HE
  734. \ICOMM header
  735. Header sets the text to be printed on top of each page. <text> is 
  736. divided into sections which are to be left justified, centered and right
  737. justified. To divide <text> into these three parts, the first character is
  738. assumed to be a separator (e.g., /left/center/right/). Any non-alphanumeric
  739. character may also be used. The character "#" is replaced with the
  740. current page number. If [n] is specified, the command acts on the indicated
  741. header line (see the ".nlheader" command); if [n] is not specified, the
  742. command acts on header line 1.
  743. \set FO .fo | .footer [n] <text>
  744. \COMM @FO
  745. \ICOMM footer
  746. Footer is identical to header except that it sets the text to be printed
  747. at the bottom of each page.  If [n] is specified, the command acts on the
  748. indicated footer line (see the ".nlfooter" command); if [n] is not specified,
  749. the command acts on footer line 2.
  750. \set OHE .oh [n] <text>
  751. \COMM @OHE
  752. \ICOMM odd header
  753. The odd header command sets the header for odd pages only.
  754. \set EHE .eh [n] <text>
  755. \COMM @EHE
  756. \ICOMM even header
  757. The even header command sets the header for even pages only.
  758. \set OFO .of [n] <text>
  759. \COMM @OFO
  760. \ICOMM odd footer
  761. The odd footer command sets the footer for odd pages only.
  762. \set EFO .ef [n] <text>
  763. \COMM @EFO
  764. \ICOMM even footer
  765. The even footer command sets the footer for even pages only.
  766. \li -5
  767. \cchar
  768. .SECT 2 3.2.4 Page Layout
  769. .index page layout
  770. .index layout, page
  771. .ap
  772.  These commands are used to specify where on the page the formatted
  773. text is to be placed.
  774.  The ".nltop" and ".nlbottom" commands set the top and
  775. bottom margins, which are the number of blank lines at the top and bottom
  776. of a page.  The ".nlheader" and ".nlfooter" commands set the number of lines
  777. in the page header and page footer areas.  The ".pl" set the total number
  778. of lines on a page, which includes the margins, headers, and footers.
  779.  The ".lm" and ".rm" commands set the left and right margins.  The left
  780. margin is the number of the column in which the first printable character
  781. appears. The right margin is the number of the column in which the last
  782. printable character appears.  Centering in the header and footer lines
  783. is done between the left and right margins.
  784.  The ".li" and ".ri" commands set the amount of left and right indentation
  785. from the left and right margins.  This is an additional amount of
  786. identation beyond that of the margins.  Centering within the text of the
  787. document is based on both the margins and indentation settings.
  788.  The ".po" (page offset) command is used to move the entire page over
  789. a given number of columns.
  790.  The general layout of a page is as follows:
  791. .br
  792. .sp
  793. .need 32
  794. .nap
  795. .FIG General Layout of a Page
  796. .nf
  797.     +----+-------------------------------------+----+ -+
  798.     |    |          top margin (.nltop)        |    |  |
  799.     +----+-------------------------------------+----+  |
  800.     |    |       header lines (.nlheader)      |    |  |
  801.     +----+-------------------------------------+----+
  802.     |    |                                     |    |  P
  803.     |    |<-- left margin (.lm)                |    |  A
  804.     |    |                  .                  |    |  G
  805.     |    |                  T                  |    |  E
  806.     |    |                  E                  |    |
  807.     |    |                  X                  |    |  L
  808.     |    |                  T                  |    |  E
  809.     |    |                  .                  |    |  N
  810.     |    |               right margin (.rm) -->|    |  G
  811.     |    |                  .                  |    |  T
  812.     |    |                  .                  |    |  H
  813.     |    |                  .                  |    |
  814.     |    |    |<-- left indent (.li)      |    |    |(.pl)
  815.     |    |    |     right indent (.ri) -->|    |    |
  816.     |    |                  .                  |    |  |
  817.     +----+-------------------------------------+----+  |
  818.     |    |      footer lines  (.nlfooter)      |    |  |
  819.     +----+-------------------------------------+----+  |
  820.     |    |      bottom margin (.nlbottom)      |    |  |
  821.     +----+-------------------------------------+----+ -+
  822.     ^
  823.     |
  824.     page offset (.po)
  825. .fi
  826. .sp 2
  827. .li +5
  828. .cchar \
  829. \set PO .po | .offset [+|-][n]
  830. \COMM @PO
  831. \ICOMM page offset
  832. \ICOMM offset
  833. The page offset command moves the entire page to the right or left
  834. depending on the
  835. specified value. All indentation is according to the page offset. PTF
  836. assumes a page offset of 0 during the startup. If [n] is specified with a
  837. plus or minus, it will be added or subtracted from the current value.
  838. \set LM .lm | .leftmargin [+|-][n]
  839. \COMM @LM 
  840. \ICOMM left margin
  841. Left Margin sets the position of the first printable character from the
  842. left edge of the page to [n]. Default value for left margin is 12.
  843. A plus or minus value will be added or subtracted from the current value.
  844. If [n] is not specified, left margin is set to the default value.
  845. \set RM .rm | .rightmargin [+|-][n]
  846. \COMM @RM 
  847. \ICOMM right margin
  848. Right Margin sets the position of the last printable character from the
  849. left edge of the page to [n]. Default value for right margin is 90.
  850. A plus or minus value will be added or subtracted from the current value.
  851. If [n] is not specified, right margin is set to the default value.
  852. \set LINDENT .in | .indent | .li | .leftindent [+|-][n]
  853. \COMM @LINDENT
  854. \ICOMM left indent
  855. Left indent causes a break and indents the following lines [n] spaces to the
  856. right of the left margin. [n] can be negative to allow beginning a line
  857. to the left of the left margin, however, a line cannot begin to the left of
  858. column 1. If a plus or minus sign is used with n, then [n] is added or
  859. subtracted to or from the current value.
  860. \set RINDENT .ri | .rightindent [+|-][n]
  861. \COMM @RINDENT
  862. \ICOMM right indent
  863. Right indent causes a break and indents the following lines [n] spaces to the
  864. left of the right margin. [n] can be negative to allow beginning a line
  865. to the right of the right margin. If a plus or minus sign is used with n,
  866. then [n] is added or
  867. subtracted to or from the current value.
  868. \set PL .pl | .ps | .pagesize [n]
  869. \COMM @PL
  870. \ICOMM page length
  871. Page length is used to set the number of lines that are to be printed
  872. on a page including the header and footer lines
  873. and top and bottom margins. After [n] lines are printed,
  874. the paper will advance to the top of next page. The default page length is
  875. 66 lines (11 inches for 6 lines/inch). This command is disabled if nopaging
  876. is set.
  877. \set M1 .nltop [n]
  878. \COMM @M1
  879. \ICOMM top margin
  880. This command
  881. sets the number of lines (not including the header) which will be left at
  882. the top of the page to [n]. The default setting is 4. If [n] is omitted, is
  883. set to the default.
  884. \set M2 .nlheader [n]
  885. \COMM @M2
  886. \ICOMM header lines
  887. \index header lines
  888. This command
  889. sets the number of header lines. The default setting is 2 so that a ".he"
  890. command will result in the header text being followed by a blank line by
  891. default.  The first of the header lines is number 1.
  892. \set M3 .nlfooter [n]
  893. \COMM @M3
  894. \ICOMM footer lines
  895. \index footer lines
  896. This command
  897. sets the number of footer lines. The default setting is 2 so that a ".fo"
  898. command will result in the footer text being preceeded by a blank line by
  899. default.  The first of the footer lines is number 1.
  900. \set M4 .nlbottom [n]
  901. \COMM @M4
  902. \ICOMM bottom margin
  903. This command
  904. sets the number of lines (not including the footer) which will be left at
  905. the bottom of the page to [n]. The default setting is 4.
  906. \li -5
  907. \cchar
  908. .ap
  909. .SECT 2 3.2.5 Table of Contents and Index
  910. .index table of contents
  911. .index contents
  912. .index index
  913.  This section describes the the commands that are used to generate a table of
  914. contents and the
  915. index. Basically, a contents line command is used in every place in
  916. the document where an entry is needed in the table of contents.
  917. Likewise,
  918. an index line command is used in every place in the document where an index
  919. entry is needed.  PTF
  920. stores the text and the page number when it encounters these commands.
  921.  After the the body of the document is processed, a print contents command
  922. dumps a contents table. The contents will be dumped with a
  923. nofill. Page numbering should be disabled or
  924. reset if the table of contents is to be
  925. used in front of the document, and auto-paragraphing should be
  926. turned off unless it is desired to double-space the
  927. contents.  PTF supports six separate contents tables, which may be used
  928. to generate tables of contents for the document as a whole, figures in
  929. the document, tables in the document, etc.  These contents tables are
  930. numbered 0 through 5, and a contents table select command is given to
  931. select one of the tables for processing.
  932.  When processing is complete, if any
  933. index entries were made, PTF will close a file named
  934. "@INDEXFILE" which contains all the index entries.  This file contains
  935. one index entry per line; each line contains the text of the index
  936. entry (left justified) and the page number of the index entry (right
  937. justified).  At the beginning of the file are two lines, each containing
  938. a single number: the first line indicates the number of columns in a
  939. text line and the second line indicates the number of text lines on a page.
  940. This information is read and used by the PTFIDX tool.
  941. The "@INDEXFILE" file may then be processed by PTFIDX
  942. or other tools
  943. to create a sorted, permuted index or whatever type of index the user
  944. wishes.
  945. .index PTFIDX
  946. .index @INDEXFILE
  947. .index index file
  948.  PTFIDX reads the "@INDEXFILE"
  949. file created by PTF and creates a new file,
  950. "@PTFIDXFILE."  This new file may then be edited by the user and processed
  951. again by PTF to produce formatted index pages.  In editing the
  952. "@PTFIDXFILE" file,
  953. .index @PTFIDXFILE
  954. the user should define the desired left and right margins,
  955. header and footer lines, and other attributes of the document he wishes
  956. to set in order to make the index output of PTF look like it belongs to
  957. the original file.
  958. .sp
  959. .li +5
  960. .ap
  961. .cchar \
  962. \set CONTSEL .contsel [table__number]
  963. \COMM @CONTSEL
  964. \ICOMM contents select
  965. The contents table select command selects one of the tables of contents
  966. (numbered 0 to 5) for processing.  Once a table is selected, the
  967. Contents Line and Print Contents commands below operate on that table.
  968. If the Table__Number option is omitted, table 0 is selected.  Tables of
  969. contents are maintained in intermediate files named "CNT0.CNT" to
  970. "CNT5.CNT"; if a Print Contents command is not issued, these files
  971. will be in the user's directory when PTF completes (the Print Contents
  972. command deletes the associated contents file).
  973. \set CL .cl | .contline [<n> <text>]
  974. \COMM @CL
  975. \ICOMM contents line
  976. Contents line specifies a line of <text> to be entered into the table of
  977. contents. <n> specifies the level at which the item is to be printed
  978. in the table. When the table is printed, each level of entry will be
  979. indented by specific number of spaces. 
  980. <text> appears in the output exactly as it appears
  981. in the contents line command, except that leading blanks are removed.
  982. If no options specified in the contents line, a blank is inserted during
  983. the table output.
  984. \set PC .pc | .printcont [n]
  985. \COMM @PC
  986. \ICOMM print contents
  987. \ICOMM contents, print
  988. Print Contents causes the currently accumulated table of contents to be
  989. printed. If [n] is specified, it is used as the indent value for each
  990. level.  If [n] is not specified, it is defaulted to 3.
  991.  A contents line at level 0 is as wide as right margin - right
  992. indent. The
  993. outlook of the table of contents may be changed by altering the right
  994. margin, left margin, right indent, and left indent values.
  995. A typical table of contents may be produced as
  996. follows:
  997. \li +5
  998. \nf
  999. \sp
  1000. \need 9
  1001. |.page
  1002. |.he ////
  1003. |.fo ////
  1004. |.nofill
  1005. |.sp
  1006. |.center
  1007. |Table of Contents
  1008. |.sp
  1009. |.printcont
  1010. \li -5
  1011. \fi
  1012. \sp
  1013. The following example illustrates the generation of a table of contents. Note
  1014. that only one table of contents is active for a PTF session.
  1015. \sp
  1016. \need 32
  1017. \cchar
  1018. .FIG Generating a Table of Contents
  1019. .cchar \
  1020. \sp
  1021. \li +5
  1022. \nf
  1023. \nap
  1024. |.cl
  1025. |.cl 0 A. Introduction
  1026. |Introduction
  1027. |        text
  1028. |.cl
  1029. |.cl 0 B. Methods
  1030. |Methods
  1031. |        text
  1032. |.cl 1 a) Sampling Procedures
  1033. |Sampling
  1034. |        text
  1035. |.cl 1 b) Laboratory Procedures
  1036. |Laboratory
  1037. |        text
  1038. |.cl
  1039. |.cl 0 C. Results
  1040. |Results
  1041. |        text
  1042. |.pg
  1043. |.nf
  1044. |.he ////
  1045. |.fo ////
  1046. |.ce
  1047. |Table of Contents
  1048. |.sp
  1049. |.pc
  1050. \sp
  1051. \cchar
  1052. .sp 2
  1053. .cchar \
  1054. \li -5
  1055. These commands will produce the following table:
  1056. \sp
  1057. \need 10
  1058. \li +2
  1059. |                Table of Contents
  1060. |
  1061. |A. Introduction...............................   1
  1062. |
  1063. |B. Methods....................................   3
  1064. |   a) Sampling Procedures.....................   3
  1065. |   b) Laboratory Procedures...................   4
  1066. |
  1067. |C. Results....................................   5
  1068. \sp
  1069. \li -2
  1070. \ap
  1071. \fi
  1072. Macros may be defined as described in the following sections to help the
  1073. generation
  1074. of the table of contents.
  1075. \set IDXL .indexlength [n]
  1076. \COMM @IDXL
  1077. \ICOMM index line
  1078. \index index line length
  1079. The index line length command sets the length of the index line in the
  1080. output file "@INDEXFILE."  If this command is not used or the numeric
  1081. argument is omitted, a default line length of 35 will be used.
  1082. \set IDX .index | .idx <text>
  1083. \COMM @IDX
  1084. \ICOMM index
  1085. \ICOMM index entry
  1086. The index entry command places an entry into the index file "@INDEXFILE."
  1087. This entry is stored with the current page number.  If the length of
  1088. the index entry text and the page number exceeds the index line length,
  1089. the index entry text will be truncated and a warning message will be
  1090. printed on the console.
  1091. \cchar
  1092. .li -5
  1093. .SECT 2 3.2.6 Defining New Commands (Macros)
  1094.  In document formatting, it is common to repeat a series of commands at
  1095. several places in the document. PTF allows you to define a new command
  1096. that will replace these repeated commands. This not only saves typing but
  1097. ensures that
  1098. .ul
  1099. exactly
  1100. the same sequence of commands are applied throughout the document. A new
  1101. command that you define is formally called a
  1102. .ul
  1103. macro.
  1104. To define a macro, you must use the define macro (.de | .define) and
  1105. end macro (.en) commands.
  1106. .li +5
  1107. .cchar \
  1108. \set DEF .de | .define <macro name>
  1109. \COMM @DEF
  1110. \ICOMM define macro
  1111. \ICOMM macro, define
  1112. Define is used to define a <macro name> to which a series of commands to
  1113. be assigned. This definition line is followed by any number of PTF
  1114. commands and/or text which define the action that the macro
  1115. will subsequently produce. Macros may refer to other macros as long as
  1116. the other macros were defined before the current macro definition.
  1117. \set ENM .en
  1118. \COMM @ENM
  1119. \ICOMM end macro
  1120. \ICOMM macro, end
  1121. End macro is the last line in the command definition. You must put in this
  1122. command to finish a currently defined macro. ".en" command should not be
  1123. re-defined as a macro.
  1124. \li -5
  1125. \sp
  1126. The example below defines macros ".NOTE" and ".ENDNOTE", similar to the
  1127. RUNOFF commands of the same name.
  1128. \li +5
  1129. \nap
  1130. \nf
  1131. \need 22
  1132. \cchar
  1133. .sp
  1134. .FIG Defining Macros
  1135. .cchar \
  1136. \sp
  1137. |
  1138. |.define NOTE
  1139. |.sp
  1140. |.ce
  1141. |NOTE
  1142. |.sp
  1143. |.fi
  1144. |.li +5
  1145. |.ri +5
  1146. |.en
  1147. |
  1148. |.define ENDNOTE
  1149. |.sp
  1150. |.nf
  1151. |.li -5
  1152. |.ri -5
  1153. |.en
  1154. |
  1155. \li -5
  1156. \ap
  1157. \fi
  1158. \cchar
  1159. .sp 2
  1160. .cchar \
  1161.  A macro is used like any other PTF command, appearing
  1162. as a control character followed
  1163. immediately by the name of the macro. The names of macros, as with all
  1164. PTF commands, are case-sensitive, so it is a good practice to
  1165. define your macros with either mixed upper- and lower-case characters
  1166. or all upper-case characters.  This ensures that your macro name will not
  1167. conflict with the name of a predefined PTF command; if this conflict
  1168. occurs, the macro definition will hide the PTF command definition.
  1169.  For example, the above macros
  1170. may be used as follows:
  1171. \li +5
  1172. \nap
  1173. \need 7
  1174. \nf
  1175. \sp
  1176. |
  1177. |.NOTE
  1178. |textextextextextextextextextext
  1179. |textextextextextextextextextext
  1180. |.ENDNOTE
  1181. |
  1182. \li -5
  1183. \sp
  1184. \fi
  1185. The following note is generated by the same macros described previously.
  1186. \cc
  1187. .nap
  1188. .NOTE
  1189. Flap's Law: Any inanimate object, regardless of its position or configuration,
  1190. may be expected to perform at any time in a totally unexpected manner for
  1191. reasons that are either entirely obscure or else completely mysterious.
  1192. .ENDNOTE
  1193. .fi
  1194. .cc \
  1195. \ap
  1196. Special symbols may be used within a macro definition. These symbols
  1197. represent
  1198. the parameters passed to a macro, delimited by blanks.
  1199. These symbols are _@0 for macro name, _@1 for the first parameter, _@2 for
  1200. the second parameter and so on, up to _@9 for the ninth parameter
  1201. and beyond (if there are 12 parameters, _@9 contains parameters
  1202. 9, 10, 11, and 12). Currently,
  1203. macro parameters may only contain any text.
  1204. The previous macro "note" may now be defined as follows:
  1205. \li +5
  1206. \sp
  1207. \nap
  1208. \nf
  1209. \need 22
  1210. \cchar
  1211. .FIG Macros with Parameters
  1212. .cchar \
  1213. \sp
  1214. |
  1215. |.define NOTE
  1216. |.sp
  1217. |.ce
  1218. |_@2 _@3 _@4 _@5 _@6 _@7 _@8 _@9
  1219. |.nr m _@1
  1220. |.sp
  1221. |.fi
  1222. |.li +_@1
  1223. |.ri +_@1
  1224. |.en
  1225. |
  1226. |.define ENDNOTE
  1227. |.sp
  1228. |.nf
  1229. |.li -_@nm
  1230. |.ri -_@nm
  1231. |.en
  1232. |
  1233. \li -5
  1234. \ap
  1235. \fi
  1236. \cchar
  1237. .sp 2
  1238. .cchar \
  1239.  In this version of the "NOTE" and "ENDNOTE" macros,
  1240. the first parameter (_@1)
  1241. is used to pass the values for left and right indentation.
  1242. All the rest of the macro parameters (_@2 to _@9) are used as the title of
  1243. the note. The indent value passed as the first parameter is also saved in the
  1244. number register "m" to communicate it to the "ENDNOTE" macro, such that
  1245. when the end note macro is called, both left and right indent values are
  1246. adjusted back to normal. It is possible and may be more useful to use
  1247. ".save" and ".restore" commands to accomplish the same task, especially if
  1248. the macro alters the current formatting context drastically. The ".NOTE"
  1249. and ".ENDNOTE" macros may be called as follows:
  1250. \li +5
  1251. \nap
  1252. \need 7
  1253. \nf
  1254. \sp
  1255. |
  1256. |.NOTE 5 Asimov's Law of Robotics
  1257. |textextextextextextextextextext
  1258. |textextextextextextextextextext
  1259. |.ENDNOTE
  1260. |
  1261. \li -5
  1262. \fi
  1263. \ap
  1264.  In this usage, the indent value will be adjusted by +5, left
  1265. and right indents will
  1266. be adjusted by +5, and the title "Asimov's Law of Robotics" will appear
  1267. centered above the note.
  1268. \cchar
  1269. .ap
  1270. .SECT 2 3.2.7 Miscellaneous
  1271.  This section describes miscellaneous commands that significantly increase the
  1272. formatting powers of PTF. With the assistance of variables, PTF can 
  1273. generate form letters and documents with dynamic parts. The ability to save
  1274. and restore formatter context eliminates the need to remember the exact
  1275. settings of the formatter across the document.
  1276. .li +5
  1277. .cchar \
  1278. \set VSET .vs | .set <variable> [definition]
  1279. \COMM @VSET
  1280. \ICOMM variable set
  1281. Set variable  defines a variable to be later used in the document.
  1282. If the definition part is left out, PTF uses the variable name as a prompt
  1283. and allows the user to define the variable interactively.
  1284. Variable names cannot
  1285. start with a numeric character, and may only contain alphanumeric 
  1286. characters. The definition of a variable may contain blanks.
  1287. All text starting with the first non-blank character after the
  1288. <variable> name to the end of the line is part of the
  1289. definition of the variable.
  1290.  Once the variable is
  1291. defined, it can be used anywhere in the document, including the command
  1292. line itself. A variable substitution is invoked by an at sign (_@). A 
  1293. literal _@ is inserted into text using ___@.
  1294. A variable name must be delimited by a non-alphanumeric character within the 
  1295. text. If the contents of the variable is to be appended to other 
  1296. alphanumeric characters, it must be surrounded by braces 
  1297. ("{" and "}"). The following is an example of variable usage:
  1298. \need 12
  1299. \sp
  1300. \nf
  1301. |.nf
  1302. |.vs v1 Murphy
  1303. |_@{v1}'s first law:
  1304. |       Nothing is as easy as it looks.
  1305. |_@{v1}'s second law:
  1306. |       Everything takes longer than you think.
  1307. |Charley's observation:
  1308. |       Computers were invented by _@v1.
  1309. |
  1310. \sp
  1311. Produces the following:
  1312. \sp
  1313. \need 8
  1314. |
  1315. |Murphy's first law:
  1316. |       Nothing is as easy as it looks.
  1317. |Murphy's second law:
  1318. |       Everything takes longer than you think.
  1319. |Charley's observation:
  1320. |       Computers were invented by Murphy.
  1321. |
  1322. \sp
  1323. \fi
  1324. \set VGET .vg | .get <variable> <prompt>
  1325. \COMM @VGET
  1326. \ICOMM variable get
  1327. Get variable is the interactive version of variable definition. In this 
  1328. variant, a prompt string is used to obtain the value of the variable,
  1329. which is typed at the user's terminal. The prompt string begins with the
  1330. first non-blank character after the <variable> name and extends to the
  1331. end of the line. 
  1332. \set VRG .nr <a-z> [+|-][n]
  1333. \COMM @VRG
  1334. \ICOMM number register
  1335. Number register is used to define registers that contain numeric values.
  1336. There are 26 number registers, named a-z. The command ".nr x n" sets the
  1337. number register "x" to value n; ".nr x +n" increments the number register
  1338. by n; ".nr x -n" decrements the number register by n. The value of the
  1339. number register x is placed in the text by the appearance of _@nx. A literal
  1340. _@ may be inserted using ___@.
  1341. Number registers may be used on command lines and anywhere in the text.
  1342. \set CCHAR .cc | .cchar [char]
  1343. \COMM @CCHAR
  1344. \ICOMM control char
  1345. \index character, control
  1346. Control Character  sets the character that distinguishes PTF 
  1347. commands from text to be formatted. As a default (and when the
  1348. ".cc" command has no arguments), control character is set to 
  1349. (".") period.
  1350. This character may be changed to something other than a period, either
  1351. to mimic other formatters or to disallow interpretation of lines beginning
  1352. with a period. This document makes heavy use of the ".cc" command.
  1353. \set ECHAR .ec | .echar [char]
  1354. \COMM @ECHAR
  1355. \ICOMM escape char
  1356. \index character, escape
  1357. Escape Character  sets the character that disallows the 
  1358. interpretation of special characters, such as "_@". PTF uses an
  1359. underline ("__") character as a default and when the ".ec" command has
  1360. no arguments.
  1361. \set FCHAR .fc | .fchar [char]
  1362. \COMM @FCHAR
  1363. \ICOMM flag char
  1364. \ICOMM character, flag
  1365. \index character, flag
  1366. Flag Character  sets the character that flags the 
  1367. variable names and number registers. PTF uses an
  1368. atsign ("_@") character as a default and when the ".fc" command has
  1369. no arguments.
  1370. \set SOU .so | .source | .include | .require <filename>
  1371. \COMM @SOU
  1372. \ICOMM include file
  1373. \ICOMM source file
  1374. The source (include) command allows external files to be inserted into the 
  1375. input file
  1376. during the formatting. Using this feature, tables, graphs and other 
  1377. documents generated outside PTF may be included into the document
  1378. being formatted. This feature is also very useful in including a common set
  1379. of macros during formatting. Include files may be nested inside other
  1380. include files. Currently, PTF only allows as many nested include
  1381. files as the memory allocation with allow.  The <filename> starts with
  1382. the first non-blank character after the ".so" verb and extends to the
  1383. end of the line.
  1384. \set SAVE .sv | .save
  1385. \COMM @SAVE
  1386. \ICOMM save
  1387. The save command allows the saving of the current formatter context on a 
  1388. pushdown stack. The saved context of the formatter includes
  1389. the following values and flags:
  1390. \need 19
  1391. \cchar
  1392. .FIG Formatter Context
  1393. .cchar \
  1394. \sp
  1395. \nf
  1396. \nap
  1397. values                  flags           on   |  off
  1398. ------                  -----
  1399. left margin     (.lm)   fill            (.fi | .nf)
  1400. right margin    (.rm)   justify         (.ju | .nj)
  1401. left indent     (.li)   auto-paragraph  (.ap | .nap)
  1402. right indent    (.ri)   paging          (.pa | .np)
  1403. page offset     (.po)   bold            (.bd | .bd)
  1404. line spacing    (.ls)   bolding        (.ebo | .dbo)
  1405. page length     (.pl)   center          (.ce | .ce)
  1406. margin values   (.nl*)  underline       (.ul | .ul)
  1407. control char    (.cc)   underlining     (.eu | .du)
  1408. escape char     (.ec)
  1409. flag char       (.fc)
  1410. \sp
  1411. \ap
  1412. \fi
  1413. \cchar
  1414. .sp 2
  1415. .cchar \
  1416. \set RST .rs | .restore
  1417. \COMM @RST
  1418. \ICOMM restore
  1419. The restore command pops the context stack and restores the values and flags
  1420. as defined above.
  1421. \set LEX .lx | .lex <command> [equate]
  1422. \COMM @LEX
  1423. \ICOMM lex
  1424. \ICOMM rename commands
  1425. \index renaming commands
  1426. The lexical modification command is essentially a permanent replacement of a
  1427. given command. This command is used for changing the command names without
  1428. resorting to the macro facility. Lex permanently removes the old
  1429. command name from command tables and replaces it with the new definition.
  1430. If the equate is not specified, the command  becomes undefined and is
  1431. no longer recognized by PTF. The command equate should not contain 
  1432. non-alphanumeric characters.
  1433. \set APR .ap
  1434. \COMM @APR
  1435. \ICOMM autoparagraph
  1436. The autoparagraph command turns on the automatic paragraphing feature. If
  1437. auto-paragraphing is on, every line that starts with a 
  1438. \ul
  1439. blank
  1440. or a 
  1441. \ul
  1442. tab
  1443. character starts a new paragraph. A new line is generated (.sp) and
  1444. the beginning of the paragraph is indented by five spaces.
  1445. Autoparagraphing is the equivalent of the following commands:
  1446. \sp
  1447. \li +5
  1448. \nf
  1449. |
  1450. |textextextextext
  1451. |.sp
  1452. |.ti +5
  1453. |textextextextext
  1454. |
  1455. \fi
  1456. \li -5
  1457. \set NAP .na | .nap
  1458. \COMM @NAP
  1459. \ICOMM no autoparagraph
  1460. No Autoparagraph command disables auto-paragraphing.
  1461. \set MSG .msg | .console | .con [text]
  1462. \COMM @MSG
  1463. \ICOMM message
  1464. \ICOMM console
  1465. The Message command sents the indicated text to the user's console.
  1466. It is useful for presenting messages to the user as the formatting is
  1467. in progress, indicating which options have been selected or where PTF
  1468. is currently working.
  1469. \set COMMENT .comment | .# | .. | .! [text]
  1470. \COMM @COMMENT
  1471. \ICOMM comment
  1472. \ICOMM .#
  1473. \ICOMM ..
  1474. \ICOMM .!
  1475. The text following the comment command is ignored (no processing is
  1476. done).  Note that at least one space must follow the comment command
  1477. verb (e.g., ".!hello" is invalid while ".! hello" is a comment).
  1478. \set WRT .wr | .write <string>
  1479. \COMM @WRT
  1480. \ICOMM special output
  1481. \ICOMM write
  1482. Write is a special output command, only to be used to configure printers
  1483. and other output devices with escape sequences. This command outputs the
  1484. associated string as it is encountered, without going through the normal
  1485. output routines of the formatter. Currently, the output string may contain
  1486. control characters specified as "^<char>", certain commonly-used
  1487. codes (alternate forms)
  1488. which are prefixed with a backslash (_\), and other characters.
  1489. Blanks within the string are not skipped.
  1490. Following is a typical string to set a Digital La-100 printer to letter
  1491. quality print mode:
  1492. \sp
  1493. \nf
  1494. \li +5
  1495. |
  1496. |.wr ^[[2z
  1497. |
  1498. \sp
  1499. \fi
  1500. \li -5
  1501. In the control string, "^[" is the ASCII equivalent of the Escape (esc)
  1502. character.
  1503. Following mapping table is used to convert characters starting with a caret
  1504. to their binary equivalents: ("|" indicates an alternative)
  1505. \nf
  1506. \nap
  1507. \sp
  1508. \need 26
  1509. \cchar
  1510. .FIG Representation of Characters Less than Space
  1511. .cchar \
  1512. \li +5
  1513. Control chr Hex Alt     Control chr Hex Alt
  1514. ----------- --- ---     ----------- --- ---
  1515. ^_@ (soh)     00         ^P (dle)     10
  1516. ^A (soh)     01         ^Q (dc1)     11
  1517. ^B (stx)     02         ^R (dc2)     12
  1518. ^C (etx)     03         ^S (dc3)     13
  1519. ^D (eot)     04         ^T (dc4)     14
  1520. ^E (enq)     05         ^U (nak)     15
  1521. ^F (ack)     06         ^V (syn)     16
  1522. ^G (bel)     07         ^W (etb)     17
  1523. ^H (bs)      08  \b     ^X (can)     18
  1524. ^I (ht)      09  \t     ^Y (em)      19
  1525. ^J (nl)      0A  \n     ^Z (sub)     1A
  1526. ^K (vt)      0B         ^[ (esc)     1B  \e
  1527. ^L (np)      0C         ^\ (fs)      1C
  1528. ^M (cr)      0D  \r     ^] (gs)      1D
  1529. ^N (so)      0E         ^^ (rs)      1E
  1530. ^O (si)      0F         ^__ (us)      1F
  1531.                         (del)        7F  \d
  1532. \sp
  1533. \li -5
  1534. \ap
  1535. \fi
  1536. \cchar
  1537. .sp 2
  1538. .li -5
  1539. .cl
  1540. .SECT 1 3.3 Executing PTF and PTFIDX
  1541. .ap
  1542. .index PTF, executing
  1543. .index executing PTF
  1544. .index PTFIDX, executing
  1545. .index executing PTFIDX
  1546.  The PTF program  may be invoked with a series of optional parameters and
  1547. filenames on the command line. The command synopsis is:
  1548. .sp
  1549. .ce
  1550. PTF [-pon] [-da] [-db] [-du] [-el] <input> [input2]* <output>
  1551. .sp
  1552.  The square brackets ([param])
  1553. indicate an optional parameter. "[param]*"
  1554. indicates zero or more "param" entries. "<param>" indicates
  1555. a required parameter.
  1556. .SECT 2 3.3.1 Command Line Parameters
  1557. Interpretation of the
  1558. parameters is as follows:
  1559. .nap
  1560. .li +10
  1561. .OPT -da
  1562. Disables all boldface and underline commands.  This command is convenient for
  1563. generating output for drafts or printers that cannot backspace.
  1564. .OPT -db
  1565. Disables all boldface commands.  This command is convenient for
  1566. generating output for drafts or printers that cannot backspace.
  1567. .OPT -du
  1568. Disables all underline commands.  This command is convenient for
  1569. generating output for drafts or printers that cannot backspace.
  1570. .OPT -el
  1571. Enables logging of errors and warnings to the file "@ERRORFILE."
  1572. .index @ERRORFILE
  1573. If this option is not specified, errors and warnings are sent to the
  1574. console.
  1575. .OPT -poN
  1576. Sets the page offset to N. This is equivalent to ".po" command within
  1577. the document. It is recommended that -poN option be used instead of
  1578. embedding the offset value within the document.  Note that there are
  1579. no spaces between the letters "po" and the number.
  1580. .OPT input [and input2, etc.]
  1581. Specifies the input files to be formatted. PTF does not impose any
  1582. file extension. The recommended extension is ".PTF".
  1583. The input files named may be actual files to be processed or include
  1584. files.  Include files are identified by being prefixed with an
  1585. ampersand (_@).
  1586. .OPT output
  1587. Specifies the output file for the formatted document. If this exists,
  1588. the user is prompted for approval to delete before proceeding.
  1589. .li -10
  1590. .ap
  1591.  PTFIDX is invoked with no parameters.  It performs only one function:
  1592. to translate the "@INDEXFILE" file
  1593. produced by PTF into a dual-column index
  1594. in a file named "@PTFIDXFILE."  The file "@PTFIDXFILE" may then be processed
  1595. by PTF to produce a formatted index.  If PTFIDX is successful, it removes
  1596. the file "@INDEXFILE."
  1597. .sp
  1598. .SECT 2 3.3.2 Include Files
  1599.  An include file contains the names of files to be processed by PTF,
  1600. the names of other include files (also prefixed with an ampersand),
  1601. blank lines, and comment lines (prefixed with a double-dash (--)).
  1602. All lines in an include file begin in column one.  An example of
  1603. an include file is:
  1604. .index include file
  1605. .sp
  1606. .li +5
  1607. .need 18
  1608. .FIG A Command Line Include File
  1609. .nf
  1610. |-- Include file for my book
  1611. |
  1612. |titlepage.ptf
  1613. |forward.ptf
  1614. |chapter1.ptf
  1615. |chapter2.ptf
  1616. |
  1617. |-- Chapter 3 is complex, containing many parts
  1618. |-- so I use another include file just to keep
  1619. |-- it in line separately
  1620. |_@chapter3.inc
  1621. |
  1622. |-- And so on
  1623. |chapter4.ptf
  1624. .fi
  1625. .li -5
  1626. .sp 2
  1627. .index include file, example of
  1628. .sp
  1629. .ap
  1630. .SECT 2 3.3.3 Examples
  1631.  Following are some examples of PTF command lines:
  1632. .index examples of executing PTF
  1633. .index executing PTF
  1634. .sp
  1635. .ul
  1636. Example:
  1637. A>PTF ptfman.ptf ptf.man
  1638.  Format this document (ptfman.prf) and output the
  1639. formatted document to the file "ptf.man".
  1640. .sp
  1641. .ul
  1642. Example:
  1643. A>PTF macros.pma ptfman.ptf ptf.man
  1644.  Format this document, include the external file "macros.pma",
  1645. and output the formatted document to the file "ptf.man".
  1646. .sp
  1647. .ul
  1648. Example:
  1649. A>PTF myprinter.pma _@mybook.inc mybook.doc
  1650.  Format the files named in the include file "mybook.inc" after processing
  1651. the printer-specific macro definitions in the file "myprinter.pma."
  1652. The formatted output goes into the file "mybook.doc."
  1653. .sp
  1654. .ul
  1655. Example:
  1656. A>PTF -po10 ptfman.prf ptf.man
  1657.  Format this document, shift the entire document by 10 spaces to right, and
  1658. output to a file called "ptf.man".
  1659. .sp
  1660. .SECT 2 3.3.4 Creating the PTF Software User's Manual
  1661.  The following is a copy of a session on a Sun workstation which illustrates
  1662. how PTF was used to create this
  1663. .ul
  1664. Software User's Manual
  1665. for PTF.  Two source files were used: ptfsum.ptf (the manual itself) and
  1666. ptfsumid.ptf (which puts together the index pages).  The session, with
  1667. comments preceeded by '#' characters, follows:
  1668. .sp
  1669. .nf
  1670. .nap
  1671. .li +2
  1672. .need 11
  1673. |host/user> # The files:
  1674. |host/user> #   PTF          -- executable PTF
  1675. |host/user> #   PTFIDX       -- executable PTFIDX
  1676. |host/user> #   PTFSUM.PTF   -- PTF source to the manual
  1677. |host/user> #   PTFSUMID.PTF -- PTF source to the index
  1678. |host/user> ls -l ptf*
  1679. |-rwxr-xr-x  1 user       278528 Aug 24 10:33 ptf
  1680. |-rwxr-xr-x  1 user       212992 Aug 24 10:33 ptfidx
  1681. |-rw-r--r--  1 user        77386 Aug 24 09:57 ptfsum.ptf
  1682. |-rw-r--r--  1 user         1760 Aug 22 15:50 ptfsumid.ptf
  1683. |
  1684. .need 7
  1685. |host/user> # This command processes the file PTFSUM.PTF
  1686. |host/user> ptf ptfsum.ptf ptf.sum
  1687. |PTF, Version 1.2
  1688. |  Output file: ptf.sum
  1689. |Warning : 4.3.A. Contents line too long - truncated
  1690. |(ptfsum.ptf: 2721)
  1691. |  No Errors,  1 Warning(s)
  1692. |
  1693. .need 5
  1694. |host/user> # The ptf command above generated these files:
  1695. |host/user> ls -l ptf.sum ptf.idx
  1696. |-rw-r--r--  1 user         5286 Aug 24 10:43 ptf.idx
  1697. |-rw-r--r--  1 user       113590 Aug 24 10:43 ptf.sum
  1698. |
  1699. .need 6
  1700. |host/user> # Now, PTFIDX will process the PTF.IDX file
  1701. |host/user> ptfidx
  1702. |PTFIDX, Version 1.2
  1703. |  ptfidx.ptf has been generated
  1704. |  No Errors, No Warnings
  1705. |
  1706. .need 5
  1707. |host/user> # It is necessary to edit PTFIDX.PTF
  1708. |host/user> # because some of the index entries
  1709. |host/user> # contain dot commands
  1710. |host/user> emacs ptfidx.ptf
  1711. |  < edit session omitted >
  1712. |
  1713. .need 8
  1714. |host/user> # Finally, the file PTFSUMID.PTF reads the
  1715. |host/user> # PTFIDX.PTF file and creates the formatted
  1716. |host/user> # index pages
  1717. |host/user> ptf ptfsumid.ptf ptfidx.sum
  1718. |PTF, Version 1.2
  1719. |  Output file: ptfidx.sum
  1720. |  No Errors, No Warnings
  1721. |
  1722. .need 3
  1723. |host/user> # PTFIDX.PTF is no longer needed
  1724. |host/user> rm ptfidx.ptf
  1725. |
  1726. .need 11
  1727. |host/user> # The result (note that PTF.IDX was removed
  1728. |host/user> # by PTFIDX when it ran earlier):
  1729. |host/user> ls -l ptf*
  1730. |-rwxr-xr-x  1 user       278528 Aug 24 10:33 ptf
  1731. |-rw-r--r--  1 user       113590 Aug 24 10:43 ptf.sum
  1732. |-rwxr-xr-x  1 user       212992 Aug 24 10:33 ptfidx
  1733. |-rw-r--r--  1 user         6928 Aug 24 10:52 ptfidx.ptf
  1734. |-rw-r--r--  1 user         7622 Aug 24 10:53 ptfidx.sum
  1735. |-rw-r--r--  1 user        77386 Aug 24 09:57 ptfsum.ptf
  1736. |-rw-r--r--  1 user         1760 Aug 22 15:50 ptfsumid.ptf
  1737. |
  1738. .need 4
  1739. |host/user> # In particular, the formatted document files:
  1740. |host/user> ls -l ptf*.sum
  1741. |-rw-r--r--  1 user       113590 Aug 24 10:43 ptf.sum
  1742. |-rw-r--r--  1 user         7622 Aug 24 10:53 ptfidx.sum
  1743. |
  1744. .need 2
  1745. |host/user> # Print the document
  1746. |host/user> lpr ptf.sum ptfidx.sum
  1747. .li -2
  1748. .fi
  1749. .sp
  1750. .ap
  1751. .cl
  1752. .SECT 1 3.4 Tips on Using PTF
  1753. .ap
  1754. .SECT 2 3.4.1 Care and Feeding of Memory
  1755. .index memory usage
  1756.  PTF uses a dynamic memory allocation scheme for some of its operations.
  1757. These are macro definitions, contents lines, variables and save context 
  1758. operation.
  1759. Running PTF under microcomputers with limited memory resources (640k or less)
  1760. require some care in using these commands:
  1761. .list 4
  1762. .item A.
  1763. Do not declare macros that are not needed within the document.
  1764. .item B.
  1765. Do not use comments within macros. Due to delayed evaluation, comments
  1766. will also be stored as a part of the macro definition.
  1767. .item C.
  1768. Where possible, avoid using too much text within macros. It is just as
  1769. easy to pass the information during the macro call.
  1770. .item D.
  1771. Use only the shortest form of commands within macros.
  1772. .item E.
  1773. Avoid unnecessary blanks within the variable definitions.
  1774. .item F.
  1775. Avoid too many context saves without a corresponding restore. The restore
  1776. operation reclaims the memory used for a save.
  1777. .nolist
  1778.  Even if the formatter is used with a system of large memory resources,
  1779. some of the precautions above are applicable (Utz's 4th law of Computer
  1780. Programming: Any given program will eventually expand to fill all the
  1781. available memory).
  1782.  
  1783. .SECT 2 3.4.2 Formatting Without Fuss
  1784.  PTF, using its default settings, may provide reasonably formatted output
  1785. in many situations.  Designed for elite type (12 characters per inch),
  1786. the default settings are sufficient to format a text file with
  1787. autoparagraphing disabled.  Placing a ".ap" command at the front of a file
  1788. turns on autoparagraphing, so the user need only know one command (.ap)
  1789. in order to start putting PTF to work.
  1790.  
  1791. .cl
  1792. .SECT 1 3.5 Examples of Macros
  1793.  The following are examples of macro definitions, use of these macros,
  1794. and the outputs they produce.  As per the recommended convention in this
  1795. manual, all macro names are in all-caps (e.g., .LIST) to distinguish them
  1796. from normal PTF commands, which are in all-lower (e.g., .sp).
  1797. .sp
  1798. .SECT 2 3.5.1 Point-Form Lists
  1799. .sp
  1800. .nf
  1801. .li +5
  1802. .need 10
  1803. .cc \
  1804. |.comment --------------- MACRO ----------------------
  1805. |.! Macros to create a point-form lists.
  1806. |.! Note the use of number registers within
  1807. |.! the macros.
  1808. |.!
  1809. |.! The macros defined below are:
  1810. |.!    LIST <indentation amount>
  1811. |.!    ITEM <token>
  1812. |.!    NOLIST
  1813. |.comment
  1814. \need 5
  1815. |.! ------------
  1816. |.define LIST
  1817. |.nr a _@1
  1818. |.li _@1
  1819. |.en
  1820. \need 6
  1821. |.! ------------
  1822. |.define ITEM
  1823. |.sp
  1824. |.ti -_@na
  1825. |_@1
  1826. |.en
  1827. \need 6
  1828. |.! ------------
  1829. |.define NOLIST
  1830. |.li -_@na
  1831. |.sp
  1832. |.en
  1833. |.! ------------
  1834.  
  1835. \li -5
  1836. \fi
  1837. The "LIST" macro is used to generate point-form lists. The first parameter
  1838. is an indent value, size of point-str + 1. A typical usage may be as 
  1839. follows:
  1840. \need 16
  1841. \li +5
  1842. \sp
  1843. \nf
  1844. |
  1845. |Project work involves:
  1846. |.sp
  1847. |.LIST 3
  1848. |.ITEM a)
  1849. |choosing a topic
  1850. |.ITEM b)
  1851. |defining the topic
  1852. |.ITEM c)
  1853. |research
  1854. |.ITEM d)
  1855. |organizing the notes
  1856. |{etc.}
  1857. |.NOLIST
  1858. |
  1859. \li -5
  1860. \sp
  1861. The above usage will produce the following:
  1862. \need 12
  1863. \li +5
  1864. \sp
  1865. |
  1866. |Project work involves:
  1867. |
  1868. |a) choosing a topic
  1869. |
  1870. |b) defining the topic
  1871. |
  1872. |c) research
  1873. |
  1874. |d) organizing the notes
  1875. |
  1876. \sp
  1877. \li -5
  1878. \fi
  1879. The point-form recommendations under section 5.1 (Care and Feeding of 
  1880. Memory) were generated with the same set of macros described above.
  1881. \cc
  1882. .sp
  1883. .SECT 2 3.5.2 Numbered Lists
  1884. .sp
  1885. .need 14
  1886. .nf
  1887. .li +5
  1888. |.comment --------------- MACRO ----------------------
  1889. |.! Macros to create numbered lists.
  1890. |.! Note the use of number registers within
  1891. |.! the macros.
  1892. |.!
  1893. |.! The macros defined below create the main list:
  1894. |.!    LIST
  1895. |.!    LE <text>
  1896. |.!    ELIST
  1897. |.! The macros defined below create the sublist:
  1898. |.!    SLIST
  1899. |.!    SLE <text>
  1900. |.!    ESLIST
  1901. |.comment
  1902. .need 5
  1903. |.! ------------
  1904. |.define LIST
  1905. |.nr a 0
  1906. |.li +5
  1907. |.en
  1908. .need 9
  1909. |.! ------------
  1910. |.define LE
  1911. |.sp
  1912. |.nr a +1
  1913. |.ti -4
  1914. |_@na.
  1915. |_@1 _@2 _@3 _@4 _@5 _@6 _@7 _@8 _@9
  1916. |.br
  1917. |.en
  1918. .need 5
  1919. |.! ------------
  1920. |.define ELIST
  1921. |.li -5
  1922. |.sp
  1923. |.en
  1924. .need 5
  1925. |.! ------------
  1926. |.define SLIST
  1927. |.nr b 0
  1928. |.li +5
  1929. |.sp
  1930. |.en
  1931. .need 9
  1932. |.! ------------
  1933. |.define SLE
  1934. |.nr b +1
  1935. |.ti -4
  1936. |_@na._@nb.
  1937. |_@1 _@2 _@3 _@4 _@5 _@6 _@7 _@8 _@9
  1938. |.br
  1939. |.en
  1940. .need 6
  1941. |.! ------------
  1942. |.define ESLIST
  1943. |.li -5
  1944. |.sp
  1945. |.en
  1946. |.! ------------
  1947. .li -5
  1948. .fi
  1949.  Using these macros, the following shows how a list may be built:
  1950. .sp
  1951. .nf
  1952. .need 14
  1953. .li +5
  1954. |.LIST
  1955. |.LE Item A
  1956. |.LE Item B
  1957. |.SLIST
  1958. |.SLE Item B.A
  1959. |.SLE Item B.B
  1960. |.ESLIST
  1961. |.LE Item C
  1962. |.SLIST
  1963. |.SLE Item C.A
  1964. |.SLE Item C.B
  1965. |.ESLIST
  1966. |.ELIST
  1967. .li -5
  1968. .fi
  1969.  The PTF commands above create a list which looks like this:
  1970. .sp
  1971. .nf
  1972. .need 12
  1973. .li +5
  1974. |
  1975. | 1.  Item A
  1976. |
  1977. | 2.  Item B
  1978. |
  1979. |      2.1.  Item B.A
  1980. |      2.2.  Item B.B
  1981. |
  1982. | 3.  Item C
  1983. |
  1984. |      3.1.  Item B.A
  1985. |      3.2.  Item B.B
  1986. .li -5
  1987. .fi
  1988.  Note how the spacing is different for sublist items (as opposed to list
  1989. items).  The reader should look closely at the macro definitions of
  1990. ".LIST," ".SLIST," ".LE," and ".SLE" to see the subtle distinction.
  1991. .sp
  1992. .SECT 2 3.5.3 Section Headings with Contents
  1993. .sp
  1994. .need 12
  1995. .nf
  1996. .li +5
  1997. |.comment --------------- MACRO ----------------------
  1998. |.! Macro used to create a section heading.  The
  1999. |.! section heading is placed into a table of contents
  2000. |.! as well as being displayed in the document.
  2001. |.!
  2002. |.! This macro is invoked by the following command:
  2003. |.!    .SECT <level> <heading number> <heading text>
  2004. |.! Parameter _@1 is the <level> number (starting at 0),
  2005. |.! Parameter _@2 is the <heading number> (like A.1 or
  2006. |.! 1.2.2.1), and the rest of the parameters are the
  2007. |.!  <heading text>
  2008. |.comment
  2009. .need 11
  2010. |.! -------------
  2011. |.define SECT
  2012. |.contline _@1 _@2 _@3 _@4 _@5 _@6 _@7 _@8 _@9
  2013. |.sp 2
  2014. |.need 10
  2015. |_@2
  2016. |.ul
  2017. |_@3 _@4 _@5 _@6 _@7 _@8 _@9
  2018. |.br
  2019. |.en
  2020. |.! -------------
  2021. .sp
  2022. .fi
  2023. .li -5
  2024.  The "SECT" macro places a section heading on the current page and
  2025. into the table of contents.  It underlines the heading text on the page.
  2026. An example of its use:
  2027. .sp
  2028. .nf
  2029. .need 5
  2030. .li +5
  2031. |.SECT 0 1 Main Section
  2032. |.SECT 1 1.1 Subsection 1
  2033. |.SECT 1 1.2 Subsection 2
  2034. |.SECT 2 1.2.1 SubSubsection 1
  2035. |.SECT 2 1.2.2 SubSubsection 2
  2036. .fi
  2037. .li -5
  2038. .sp
  2039.  The output (in the document) produced by these five commands is:
  2040. .sp
  2041. .need 15
  2042. .li +5
  2043. |
  2044. .br
  2045. |
  2046. .br
  2047. |1
  2048. .ul
  2049. Main Section
  2050. .br
  2051. |
  2052. .br
  2053. |
  2054. .br
  2055. |1.1
  2056. .ul
  2057. Subsection 1
  2058. .br
  2059. |
  2060. .br
  2061. |
  2062. .br
  2063. |1.2
  2064. .ul
  2065. Subsection 2
  2066. .br
  2067. |
  2068. .br
  2069. |
  2070. .br
  2071. |1.2.1
  2072. .ul
  2073. SubSubsection 1
  2074. .br
  2075. |
  2076. .br
  2077. |
  2078. .br
  2079. |1.2.2
  2080. .ul
  2081. SubSubsection 2
  2082. .br
  2083. .li -5
  2084. .sp
  2085.  The output (in the table of contents) produced by these five commands will
  2086. be something like this (assuming that the default level indentation of
  2087. 3 is used):
  2088. .sp
  2089. .need 5
  2090. .nf
  2091. .li +5
  2092. |1 Main Section ..................................... 1
  2093. |   1.1 Subsection 1 ................................ 1
  2094. |   1.2 Subsection 2 ................................ 1
  2095. |      1.2.1 SubSubsection 1 ........................ 1
  2096. |      1.2.2 SubSubsection 2 ........................ 1
  2097. .li -5
  2098. .fi
  2099. .sp
  2100. .bp
  2101. .cl
  2102. .SECT 0 4 Error messages
  2103.  Three kinds of error messages are generated by PTF: (1) conventional
  2104. error messages, which indicate an error that may be readily corrected
  2105. by the user, (2) internal error messages, which indicate an internal
  2106. error (usually dynamic memory allocation problems) that may or may not
  2107. be readily corrected by the user, and (3) warning messages, on which
  2108. the user may or may not wish to take action.  Each error message
  2109. has an associated error code (which may be used by a programmer to
  2110. isolate its source -- see the
  2111. .ul
  2112. PTF Software Programmer's Manual
  2113. for more information).  Internal errors begin with the words "Internal
  2114. error."
  2115.  Each error and warning message is prefixed with "Error:" or "Warning:"
  2116. and is suffixed with the name of the input file and the number of the line
  2117. in the input file at which the error was encountered ("(filename: line)").
  2118. Each error message is also numbered as per the paragraph and list numbering
  2119. below for ease of lookup (e.g., Error__Create is number 4.1.A).
  2120. .ec \
  2121. .SECT 1 4.1 Conventional Error Messages
  2122.  The conventional error messages, which indicate errors that may be
  2123. readily corrected by the user, are listed below.
  2124. .list 4
  2125. .item A.
  2126. Error_Create
  2127. .br
  2128. "Cannot create output file"
  2129. .PP
  2130. Self-explanatory.
  2131. .item B.
  2132. Error_Delete_File
  2133. .br
  2134. "Cannot delete old output file"
  2135. .PP
  2136. Self-explanatory.
  2137. .item C.
  2138. Error_Expansion
  2139. .br
  2140. "Not enough room to expand line"
  2141. .PP
  2142. During the processing of each text line, the text line is expanded.
  2143. Variable references (\@variable or \@nx)
  2144. are replaced by the values of the variables or number registers.
  2145. Tabs are replaced the the appropriate number of spaces.  If the internal
  2146. buffer used for this expansion overflows, this error message is printed.
  2147. A solution is to remove tabs (if not required) or to break the line
  2148. into two shorter pieces (if possible).
  2149. .item D.
  2150. Error_Fatal
  2151. .br
  2152. "Unexpected fatal error"
  2153. .PP
  2154. Self-explanatory.  Something unexpected has caused PTF to halt
  2155. processing.  The file name and line number should be the starting
  2156. point for figuring out what the problem.
  2157. .item E.
  2158. Error_Hf_Lines
  2159. .br
  2160. "Range error on number of header or footer lines"
  2161. .PP
  2162. The number of a header line or a footer line was zero (0) or exceeded
  2163. the number of header or footer line allowed by the default settings
  2164. or the .nlheader and .nlfooter commands.
  2165. .item F.
  2166. Error_Include
  2167. .br
  2168. "Error in include file: <filename>"
  2169. .PP
  2170. The named include file could not be found or there was some
  2171. problem with it.
  2172. .item G.
  2173. Error_Indent
  2174. .br
  2175. "Indentation would move to before page boundary"
  2176. .PP
  2177. A .lm, .li, or .ti command would move the starting position of the first
  2178. character in the next line to before the first character on the page.
  2179. .item H.
  2180. Error_Index_File_Create
  2181. .br
  2182. "Cannot create index file"
  2183. .PP
  2184. Self-explanatory.
  2185. .item I.
  2186. Error_Invalid_Option
  2187. .br
  2188. "Invalid option (not -db or -po#) in command line"
  2189. .PP
  2190. Self-explanatory.
  2191. .item J.
  2192. Error_Lex
  2193. .br
  2194. "No arguments given to .lex command"
  2195. .PP
  2196. Self-explanatory.
  2197. .item K.
  2198. Error_Macro
  2199. .br
  2200. "Error in macro definition"
  2201. .PP
  2202. Self-explanatory.  Applies to the .define command.
  2203. .item L.
  2204. Error_Macro_End
  2205. .br
  2206. "Isolated macro end (.en) encountered"
  2207. .PP
  2208. An .en command was found with no corresponding .define.
  2209. .item M.
  2210. Error_Macro_Unknown_Command
  2211. .br
  2212. "Unknown command/macro in macro definition"
  2213. .PP
  2214. While processing and storing a macro definition, a command was encountered
  2215. which is not defined as part of PTF or as another macro.  Note that
  2216. macro definitions are forward-reference only, so all macros referenced
  2217. by a macro definition must be first defined.
  2218. .item N.
  2219. Error_Margin
  2220. .br
  2221. "Left starting column greater than right"
  2222. .PP
  2223. The left indent and left margin add up to a starting column greater
  2224. than the right margin minus the right indent.
  2225. .item O.
  2226. Error_Number
  2227. .br
  2228. "Numeric conversion problem on <string>"
  2229. .PP
  2230. The indicated string could not be converted to a number (it contains
  2231. something other than the digits 0-9).
  2232. .item P.
  2233. Error_Number_Register
  2234. .br
  2235. "Error in number register definition <string>"
  2236. .PP
  2237. The indicated string contains something other than the
  2238. single lower-case letter a-z which represents a number register.
  2239. .item Q.
  2240. Error_Page_Number_Format
  2241. .br
  2242. "Invalid page number format requested"
  2243. .PP
  2244. In a .pn command, a starting character other than
  2245. "a" for Arabic, "l" for lower-case Roman, or "u" for upper-case
  2246. Roman was specified.
  2247. .item R.
  2248. Error_Source_File
  2249. .br
  2250. "Error in processing source file"
  2251. .PP
  2252. A fatal error was encountered while processing
  2253. the indicated file.  This file may be a file
  2254. specified on the command line (or in an include file
  2255. referenced on the command line) or a file referenced
  2256. by a .include command.
  2257. .item S.
  2258. Error_Spaceto
  2259. .br
  2260. "Spaceto request is before current line"
  2261. .PP
  2262. A .st command's argument evaluated to a line before
  2263. the current line.
  2264. .item T.
  2265. Error_Stack_Empty
  2266. .br
  2267. "Restore requested of an empty stack"
  2268. .PP
  2269. A .restore command was issued without a corresponding .save
  2270. command.
  2271. .item U.
  2272. Error_Stack_Overflow
  2273. .br
  2274. "Save resulted in an overflow of the stack -- save not done"
  2275. .PP
  2276. Self-explanatory.  This is caused by running out of dynamic memory.
  2277. .item V.
  2278. Error_Unknown
  2279. .br
  2280. "Unknown command"
  2281. .PP
  2282. Self-explanatory.
  2283. .item W.
  2284. Error_User_Abort
  2285. .br
  2286. "User Abort"
  2287. .PP
  2288. This message is printed when the user requests an
  2289. abort of PTF.
  2290. .item X.
  2291. Error_Write
  2292. .br
  2293. "Write command buffer overflow"
  2294. .PP
  2295. A .wr command resulted in an overflow of the internal
  2296. buffer used to hold the binary image which will be output.
  2297. Try breaking up the .wr command into two successive
  2298. commands or put a line break (.br) command somewhere in the
  2299. string being output.
  2300. .item Y.
  2301. Error_Variable_Set
  2302. .br
  2303. "Error in variable get or set command"
  2304. .PP
  2305. Self-explanatory.
  2306. .item Z.
  2307. Error_Variable_Name
  2308. .br
  2309. "Variable not found"
  2310. .PP
  2311. Self-explanatory.
  2312. .nolist
  2313. .SECT 1 4.2 Internal Error Messages
  2314.  Internal error messages, which indicate internal errors (usually
  2315. dynamic memory allocation problems) that may or may not be readily
  2316. corrected by the user, are listed below.  These messages are simply
  2317. listed below without further explanation; this information is useful
  2318. mainly to a programmer.
  2319. .list 4
  2320. .item A.
  2321. Error_Internal_Add_Index_Entry
  2322. .br
  2323. "Internal error in Index.Add_Entry"
  2324. .item B.
  2325. Error_Internal_Add_Line
  2326. .br
  2327. "Internal error in Contents.Add_Line"
  2328. .item C.
  2329. Error_Internal_Break_Line
  2330. .br
  2331. "Internal error in FOF.Break_Line"
  2332. .item D.
  2333. Error_Internal_Break_Page_1
  2334. .br
  2335. "Internal error in FOF.Break_Page (1st routine)"
  2336. .item E.
  2337. Error_Internal_Break_Page_2
  2338. .br
  2339. "Internal error in FOF.Break_Page (2nd routine)"
  2340. .item F.
  2341. Error_Internal_Bottom
  2342. .br
  2343. "Internal error in FOF.Output_Bottom_Of_Page"
  2344. .item G.
  2345. Error_Internal_Hf_Line
  2346. .br
  2347. "Internal error in FOF.Put_Header_Footer_Line"
  2348. .item H.
  2349. Error_Internal_Identify
  2350. .br
  2351. "Internal error in Command.Identify"
  2352. .item I.
  2353. Error_Internal_Increment
  2354. .br
  2355. "Internal error in Variable. Increment_Line_Number"
  2356. .item J.
  2357. Error_Internal_Macro_Define
  2358. .br
  2359. "Internal error in Macro.Define_Parameters"
  2360. .item K.
  2361. Error_Internal_Macro_Write
  2362. .br
  2363. "Internal error in Macro.Write"
  2364. .item L.
  2365. Error_Internal_Open
  2366. .br
  2367. "Internal error in Word_Processor. Open_Output_File"
  2368. .item M.
  2369. Error_Internal_Pnum
  2370. .br
  2371. "Internal error in FOF.Pnum_As_String"
  2372. .item N.
  2373. Error_Internal_Process
  2374. .br
  2375. "Internal error in Command.Process"
  2376. .item O.
  2377. Error_Internal_Print
  2378. .br
  2379. "Internal error in Contents.Print"
  2380. .item P.
  2381. Error_Internal_Put_Invisible
  2382. .br
  2383. "Internal error in FOF.Put_Invisible_Word"
  2384. .item Q.
  2385. Error_Internal_Put_Line
  2386. .br
  2387. "Internal error in FOF.Put_Line"
  2388. .item R.
  2389. Error_Internal_Put_What
  2390. .br
  2391. "Internal error in FOF.Put_Word.Put_What"
  2392. .item S.
  2393. Error_Internal_Put_Word
  2394. .br
  2395. "Internal error in FOF.Put_Word"
  2396. .item T.
  2397. Error_Internal_Set_Footer_Line
  2398. .br
  2399. "Internal error in FOF.Set_Footer_Line"
  2400. .item U.
  2401. Error_Internal_Set_Header_Line
  2402. .br
  2403. "Internal error in FOF.Set_Header_Line"
  2404. .item V.
  2405. Error_Internal_Set_Var
  2406. .br
  2407. "Internal error in Variable.Set_Var"
  2408. .item W.
  2409. Error_Internal_Skip
  2410. .br
  2411. "Internal error in FOF.Skip"
  2412. .item X.
  2413. Error_Internal_Top
  2414. .br
  2415. "Internal error in FOF.Output_Top_Of_Page"
  2416. .item Y.
  2417. Error_Internal_PTFIDX
  2418. .br
  2419. "Internal error in PTFIDX"
  2420. .nolist
  2421. .SECT 1 4.3 Warning Messages
  2422.  Warning messages, on which the user may or may not wish to take
  2423. action, are listed below.
  2424. .list 4
  2425. .item A.
  2426. Warning_Contents_Line_Truncation
  2427. .br
  2428. "Contents line too long - truncated"
  2429. .PP
  2430. A contents line placed into the table of contents by the .pc
  2431. command is too long, and truncation has occurred.  The user may
  2432. wish to check out the final table of contents, identify the line that
  2433. has been truncated, and then shorten its text in the .cl line in the
  2434. source file.
  2435. .item B.
  2436. Warning_Contents_Number
  2437. .br
  2438. "Invalid contents number - table 0 selected"
  2439. .PP
  2440. In a .contsel command, a number other than 0-5 was specified.
  2441. Contents table 0 was selected.
  2442. .item C.
  2443. Warning_Index_Line_Truncation
  2444. .br
  2445. "Index line too long - truncated"
  2446. .PP
  2447. An index line placed into the "@INDEXFILE"
  2448. file being generated was too
  2449. long to fit.  The user may wish to shorten it, lengthen the
  2450. line length of the index file (.indexlength command), or allow the line to
  2451. be truncated.
  2452. .item D.
  2453. Warning_Index_Width
  2454. .br
  2455. "Index line too wide (index not in margins)"
  2456. .PP
  2457. An index line (generated by PTF and used by PTFIDX) should be less
  2458. than half of the length of the line (from left margin to right margin)
  2459. of the document processed by PTF.  If not, the index will not appear
  2460. correctly on the pages generated by PTFIDX.
  2461. .item E.
  2462. Warning_Table_Empty
  2463. .br
  2464. "Current contents table is empty"
  2465. .PP
  2466. The current table of contents does not contain any entries.
  2467. This message appears in response to a .pc command.
  2468. .nolist
  2469. .ec
  2470. .bp
  2471. .cl
  2472. .SECT 0 5 Notes
  2473. .SECT 1 5.1 Acronyms
  2474. .include ptfacr.ptf
  2475. .SECT 1 5.2 Acknowledgements
  2476.  This document is based in part on the original
  2477. .ul
  2478. PROFF User's Guide.
  2479. It is also based on the DoD-STD-2167A Software User's Manual
  2480. Data Item Descriptor (DI-MCCR-80019A).
  2481.  The original
  2482. .ul
  2483. PROFF User's Guide
  2484. was written by Ozan Yigit and Steven Tress
  2485. and edited by Terry Lim and Steven Tress.
  2486. The format of that document is largely based on The Freshwater Institute
  2487. RUNOFF User's Guide.
  2488.  The Quotes for the various formatting examples are
  2489. from THE QUOTABLE NOTHING BOOK and from 1001 LOGICAL LAWS, ACCURATE
  2490. AXIOMS, PROFOUND PRINCIPLES, TRUSTY TRUISMS, HOMEY HOMILIES, COLORFUL
  2491. COROLLARIES, QUOTABLE QUOTES, AND RAMBUNCTIOUS RUMINATIONS FOR ALL
  2492. WALKS OF LIFE, by Peers, Bennet and Booth, Fawcett Columbine Books,
  2493. New York.
  2494. .bp 1
  2495. .pn arabic A-#
  2496. .cl
  2497. .SECT 0 A. Summary of PTF Commands
  2498. .nap
  2499. .sp 2
  2500. .SECT 1 A.1 Filling and Justifying Commands
  2501. .nf
  2502. .sp
  2503. .cc \
  2504. \sp
  2505. ----------------------------------------------------------
  2506. @FILL
  2507.                 initial: yes    break: yes
  2508.         Begin filling output lines.
  2509. ----------------------------------------------------------
  2510. @NOFILL
  2511.                 initial: no    break: yes
  2512.         Stop filling.
  2513. ----------------------------------------------------------
  2514. @JUST
  2515.                 initial: yes    break: yes
  2516.         Begin justifying filled lines.
  2517. ----------------------------------------------------------
  2518. @NOJUST
  2519.                 initial: no    break: yes
  2520.         Stop justifying.
  2521. ----------------------------------------------------------
  2522. \cc
  2523. .ne 48
  2524. .sp
  2525. .fi
  2526. .SECT 1 A.2 Text Formatting Commands
  2527. .nf
  2528. .sp
  2529. .cc \
  2530. \sp
  2531. ----------------------------------------------------------
  2532. @BREAK
  2533.                         break: yes
  2534.         Cause a break and output current line.
  2535. ----------------------------------------------------------
  2536. @TINDENT
  2537.         default: 0            break: yes
  2538.         Temporarily indent next output n spaces.
  2539. ----------------------------------------------------------
  2540. @SPACETO
  2541.         default: 0             break: yes
  2542.         Space to line +n from top or -n from
  2543.                 bottom.
  2544. ----------------------------------------------------------
  2545. @SPACE
  2546.         default: 1     initial: 1    break: yes
  2547.         Space n lines except at top of page.
  2548. ----------------------------------------------------------
  2549. @CENTER
  2550.         default: 1            break: yes
  2551.         Center next n lines or until turned off.
  2552. ----------------------------------------------------------
  2553. @UNDLINE
  2554.         default: 1    initial        break: no
  2555.         Underline next n lines or until turned off.
  2556. ----------------------------------------------------------
  2557. @DU
  2558.                 initial: no    break: no
  2559.         Disable underlining.
  2560. ----------------------------------------------------------
  2561. @EU
  2562.                 initial: yes    break: no
  2563.         Enable underlining.
  2564. ----------------------------------------------------------
  2565. @CUNDLINE
  2566.         default: words    initial: words    break: no
  2567.         Set mode for underline - non-punctuation
  2568.                 characters or all non-blank characters.
  2569. ----------------------------------------------------------
  2570. @BOLD
  2571.         default: 1            break: no
  2572.         Boldface (overstrike) next n lines or
  2573.         until turned off.
  2574. ----------------------------------------------------------
  2575. \cc
  2576. .ne 16
  2577. .sp
  2578. .fi
  2579. .SECT 1 A.2 Text Formatting Commands, Continued
  2580. .nf
  2581. .sp
  2582. .cc \
  2583. \sp
  2584. ----------------------------------------------------------
  2585. @DBO
  2586.                 initial: no    break: no
  2587.         Disable bolding.
  2588. ----------------------------------------------------------
  2589. @EBO
  2590.                 initial: yes    break: no
  2591.         Enable bolding.
  2592. ----------------------------------------------------------
  2593. \cc
  2594. .ne 30
  2595. .sp
  2596. .fi
  2597. .SECT 1 A.3 Page Formatting Commands
  2598. .nf
  2599. .sp
  2600. .cc \
  2601. \sp
  2602. ----------------------------------------------------------
  2603. @LS
  2604.         default: 1    initial: 1    break: no
  2605.         Set line spacing to n.
  2606. ----------------------------------------------------------
  2607. @BP
  2608.         default: +1    initial: 1    break: yes
  2609.         Begin a new page and number it n.
  2610. ----------------------------------------------------------
  2611. @PN
  2612.         default: arabic    initial: arabic    break: no
  2613.         Set page numbering to arabic, lower-case
  2614.                 Roman, or upper-case Roman.  Define page
  2615.                 number text.
  2616. ----------------------------------------------------------
  2617. @NPA
  2618.                 initial: no    break: yes
  2619.         Disable paging.
  2620. ----------------------------------------------------------
  2621. @PA
  2622.                 initial: yes    break: yes
  2623.         Enable paging.
  2624. ----------------------------------------------------------
  2625. @NE
  2626.         default: 0            break: yes/no
  2627.         Need n lines. Break and generate a new page
  2628.         if not available.
  2629. ----------------------------------------------------------
  2630. \cc
  2631. .ne 40
  2632. .sp
  2633. .fi
  2634. .SECT 1 A.4 Page Formatting Commands, Headers and Footers
  2635. .nf
  2636. .sp
  2637. .cc \
  2638. \sp
  2639. ----------------------------------------------------------
  2640. @HE
  2641.                 initial: null    break: no
  2642.         Set header to text (/left/center/right/).
  2643. ----------------------------------------------------------
  2644. @FO
  2645.                 initial: null    break: no
  2646.         Set footer to text (/lef/center/right/).
  2647. ----------------------------------------------------------
  2648. @OHE
  2649.                 initial: null    break: no
  2650.         Set header on odd pages to text.
  2651. ----------------------------------------------------------
  2652. @EHE
  2653.                 initial: null    break: no
  2654.         Set header on even pages to text.
  2655. ----------------------------------------------------------
  2656. @OFO
  2657.                 initial: null    break: no
  2658.         Set footer on odd pages to text.
  2659. ----------------------------------------------------------
  2660. @EFO
  2661.                 initial: null    break: no
  2662.         Set footer on even pages to text.
  2663. ----------------------------------------------------------
  2664. \cc
  2665. .ne 46
  2666. .sp
  2667. .fi
  2668. .SECT 1 A.5 Page Layout Commands
  2669. .nf
  2670. .sp
  2671. .cc \
  2672. \sp
  2673. ----------------------------------------------------------
  2674. @PO
  2675.         default: 0    initial: 0    break: yes
  2676.         Set page offset to n spaces.
  2677. ----------------------------------------------------------
  2678. @LM 
  2679.         default: no chg    initial: 12    break: yes
  2680.         Set left margin to column n.
  2681. ----------------------------------------------------------
  2682. @RM 
  2683.         default: no chg    initial: 90    break: yes
  2684.         Set right margin to column n.
  2685. ----------------------------------------------------------
  2686. @LINDENT
  2687.         default: no chg    initial: 0    break: yes
  2688.         Set left indent by n columns.  +n moves in
  2689.                 and -n moves out (to the left).
  2690. ----------------------------------------------------------
  2691. @RINDENT
  2692.         default: no chg    initial: 0    break: yes
  2693.         Set right indent by n columns. +n moves in
  2694.                 and -n moves out (to the right).
  2695. ----------------------------------------------------------
  2696. @PL
  2697.         default: 66    initial: 66    break: no
  2698.         Set page length to n lines.
  2699. ----------------------------------------------------------
  2700. @M1
  2701.         default: 4    initial: 4    break: no
  2702.         Number of lines at top of page before the
  2703.                 header lines.
  2704. ----------------------------------------------------------
  2705. @M2
  2706.         default: 2    initial: 2    break: no
  2707.         Number of header lines.
  2708. ----------------------------------------------------------
  2709. @M3
  2710.         default: 2     initial: 2    break: no
  2711.         Number of footer lines.
  2712. ----------------------------------------------------------
  2713. @M4
  2714.         default: 4    initial: 4    break: no
  2715.         Number of lines at bottom of page after
  2716.                 the footer lines.
  2717. ----------------------------------------------------------
  2718. \cc
  2719. .ne 20
  2720. .sp
  2721. .fi
  2722. .SECT 1 A.6 Table of Contents Commands
  2723. .nf
  2724. .sp
  2725. .cc \
  2726. \sp
  2727. ----------------------------------------------------------
  2728. @CONTSEL
  2729.         default: 0    initial: 0    break: no
  2730.         Select table of contents 0-5.
  2731. ----------------------------------------------------------
  2732. @CL
  2733.         default: no chg    initial: 0    break: yes
  2734.         Enter text into table of contents at
  2735.                 level n.
  2736. ----------------------------------------------------------
  2737. @PC
  2738.         default: 3    initial: 3    break: yes
  2739.         Print table of contents, indent each level
  2740.         n spaces.
  2741. ----------------------------------------------------------
  2742. @IDX
  2743.                         break: no
  2744.         Make an index entry into the index
  2745.                 file "@INDEXFILE."
  2746. ----------------------------------------------------------
  2747. @IDXL
  2748.         default: no chg    initial: 35    break: no
  2749.         Set length of index line in "@INDEXFILE."
  2750. ----------------------------------------------------------
  2751. \cc
  2752. .sp 4
  2753. .ne 12
  2754. .fi
  2755. .SECT 1 A.7 Defining New Commands (Macros)
  2756. .nf
  2757. .sp
  2758. .cc \
  2759. \sp
  2760. ----------------------------------------------------------
  2761. @DEF
  2762.                         break: no
  2763.         Define a macro command - ends at ".en".
  2764. ----------------------------------------------------------
  2765. @ENM
  2766.                         break: no
  2767.         End the macro definition.
  2768. ----------------------------------------------------------
  2769. \cc
  2770. .bp
  2771. .fi
  2772. .SECT 1 A.8 Miscellaneous Commands
  2773. .nf
  2774. .sp
  2775. .cc \
  2776. \sp
  2777. ----------------------------------------------------------
  2778. @VSET
  2779.                         break: no
  2780.         Set variable to text.
  2781. ----------------------------------------------------------
  2782. @VGET
  2783.                         break: no
  2784.         Set variable interactively, using text
  2785.         as prompt.
  2786. ----------------------------------------------------------
  2787. @VRG
  2788.                 initial: 0    break: no
  2789.         Set number register (a-z) to n.
  2790. ----------------------------------------------------------
  2791. @CCHAR
  2792.         default: "."    initial: "."    break: no
  2793.         Set command control character.
  2794. ----------------------------------------------------------
  2795. @ECHAR
  2796.         default: "__"    initial: "__"    break: no
  2797.         Set universal escape character.
  2798. ----------------------------------------------------------
  2799. @FCHAR
  2800.         default: "_@"    initial: "_@"    break: no
  2801.         Set the variable and register flag char.
  2802. ----------------------------------------------------------
  2803. @SOU
  2804.                 initial: input    break: no
  2805.         Switch input to file.
  2806. ----------------------------------------------------------
  2807. @SAVE
  2808.                         break: yes
  2809.         Save the current formatter context on 
  2810.         context stack.
  2811. ----------------------------------------------------------
  2812. @RST
  2813.                         break: yes
  2814.         Restore the formatter context from context
  2815.         stack.
  2816. ----------------------------------------------------------
  2817. @LEX
  2818.                         break: no
  2819.         Rename a command.
  2820. ----------------------------------------------------------
  2821. \cc
  2822. .bp
  2823. .fi
  2824. .SECT 1 A.8 Miscellaneous Commands, continued
  2825. .nf
  2826. .sp
  2827. .cc \
  2828. \sp
  2829. ----------------------------------------------------------
  2830. @APR
  2831.                 initial: no    break: no
  2832.         Enable auto-paragraphing.
  2833. ----------------------------------------------------------
  2834. @NAP
  2835.                 initial: yes    break: no
  2836.         Disable auto-paragraphing.
  2837. ----------------------------------------------------------
  2838. @MSG
  2839.                         break: no
  2840.         Write a message to the console.
  2841. ----------------------------------------------------------
  2842. @COMMENT
  2843.                         break: no
  2844.         Enter a comment.
  2845. ----------------------------------------------------------
  2846. @WRT
  2847.                         break: no
  2848.         Write a special string to output. Line
  2849.         length counter does not change.
  2850. ----------------------------------------------------------
  2851. \cc
  2852. .comment
  2853. .! The table of contents is automatically generated and placed
  2854. .! here in the document file.  It should be physically moved to
  2855. .! after the title page after printing the document.
  2856. .comment
  2857. .bp 2
  2858. .pn lower_roman #
  2859. .ce
  2860. .ul
  2861. Table of Contents
  2862. .sp 2
  2863. .pc
  2864. .sp 10
  2865. .ne 20
  2866. .ce
  2867. .ul
  2868. List of Figures
  2869. .sp 2
  2870. .PRFIG
  2871. .comment
  2872. .! This is provided in case the table of contents ends on an odd
  2873. .! page number.
  2874. .comment
  2875. .bp
  2876. .sp 20
  2877. .ce
  2878. This page intentionally blank
  2879. --::::::::::
  2880. --ptfsumid.ptf
  2881. --::::::::::
  2882. .comment
  2883. .! Index to Software User's Manual (2167A, DI-MCCR-80019A) for:
  2884. .!   PORTABLE TEXT FORMATTER (PTF)
  2885. .! Prepared by: Richard Conn
  2886. .! Date:        5/7/90
  2887. .! Modifications
  2888. .! 08/18/89  1.0  Rick Conn  Initial Version
  2889. .! 02/27/90  1.1  Rick Conn  PTFPCR-01 to PTFPCR-04
  2890. .! 05/07/90  1.2  Rick Conn  PTFPCR-05 to PTFPCR-06
  2891. .!
  2892. .! Description and Purpose:
  2893. .!   1. The Software User's Manual (SUM) provides user personnel
  2894. .! with instructions sufficient to execute one or more related
  2895. .! Computer Software Configuration Items (CSCIs).
  2896. .!   2. The SUM provides the steps for executing the software, the
  2897. .! expected output, and the measures to be taken if error messages
  2898. .! appear.
  2899. .!   3. The information required by this DID (Data Item Descriptor)
  2900. .! is directed to the functional user of the CSCI(s), as opposed
  2901. .! to the operator of the computer system.  If this distinction does
  2902. .! not exist, the user will need to refer to both the Computer
  2903. .! System Operator's Manual and the SUM to operate the computer system
  2904. .! and to use the CSCI(s).
  2905. .!
  2906. .! Tailoring Instructions:
  2907. .!    To tailor this template, fill in the areas surrounded by
  2908. .! [] as indicated.
  2909. .comment
  2910.  
  2911. .comment
  2912. .! This is set for PICA type (10 chars/inch).  Change accordingly
  2913. .! for ELITE or other type styles.  Also, the default top and bottom
  2914. .! margins and headers are used, giving 1 inch top and bottom for
  2915. .! both margins and headers at 6 lines/inch.  No auto-paragraphing.
  2916. .comment
  2917. .lm 11
  2918. .rm 70
  2919.  
  2920. .comment
  2921. .! Set the page heading to contain the Document Control
  2922. .! Number and date.  The Document Control Number contains
  2923. .! revision and volume identification as applicable.
  2924. .! PTF 1.2 Software User's Manual
  2925. .comment
  2926. .he //PTF 1.2 Software User's Manual//
  2927. .fo //Index-#//
  2928. .comment
  2929. .! The PTFIDX.PTF file generated by PTFIDX.
  2930. .! Be sure to edit the file named below in case any dot commands are
  2931. .! a part of the index.
  2932. .comment
  2933. .include ptfidx.ptf
  2934. --::::::::::
  2935. --ptfvdd.ptf
  2936. --::::::::::
  2937. .comment
  2938. .! Version Description Document (2167A, DI-MCCR-80013A) for:
  2939. .!   Portable Text Formatter (PTF)
  2940. .! Prepared by: Richard Conn
  2941. .! Date:        5/7/90
  2942. .! Modifications
  2943. .! 08/24/89  1.0  Rick Conn  Initial Version
  2944. .! 02/27/90  1.1  Rick Conn  PTFPCR-1 to PTFPCR-4 Fixes
  2945. .! 05/07/90  1.2  Rick Conn  PTFPCR-5 and PTFPCR-6 Fixes
  2946. .!
  2947. .! Description and Purpose:
  2948. .!   1. The Version Description Document (VDD) identifies and describes
  2949. .! a version of a Computer Software Configuration Item (CSCI).
  2950. .!   2. The VDD isused by the contractor to release CSCI versions to
  2951. .! the Government.  The term "version" may be applied to the initial
  2952. .! release of a CSCI, to a subsequent release of that CSCI, or to one
  2953. .! of multiple forms of the CSCI released at approximately the same
  2954. .! time (e.g., to different sites).
  2955. .!   3. The VDD is used by the Government to track and control versions
  2956. .! of software to be released to the operational environment.
  2957. .!
  2958. .! Tailoring Instructions:
  2959. .!    To tailor this template, fill in the areas surrounded by
  2960. .! [] as indicated.
  2961. .comment
  2962.  
  2963. .comment
  2964. .! This is set for PICA type (10 chars/inch).  Change accordingly
  2965. .! for ELITE or other type styles.  Also, the default top and bottom
  2966. .! margins and headers are used, giving 1 inch top and bottom for
  2967. .! both margins and headers at 6 lines/inch.  No auto-paragraphing.
  2968. .comment
  2969. .lm 11
  2970. .rm 70
  2971.  
  2972. .comment
  2973. .! The following reads in a set of macros used by all the 2167A
  2974. .! document templates.
  2975. .comment
  2976. .include zzz2167a.ptf
  2977.  
  2978. .comment
  2979. .! Set the page heading to contain the Document Control
  2980. .! Number and date.  The Document Control Number contains
  2981. .! revision and volume identification as applicable.
  2982. .comment
  2983. .he //PTF 1.2 Version Description Document//
  2984.  
  2985. .ce on
  2986.  
  2987. .comment
  2988. .! The next line contains the revision indicator and the
  2989. .! date of revision.
  2990. .comment
  2991.  
  2992. Version 1.2: 7 May 1990
  2993.  
  2994. .spaceto +15
  2995. VERSION DESCRIPTION DOCUMENT
  2996. .sp
  2997. FOR THE
  2998. .sp
  2999. .comment
  3000. .! The name of the CSCI appears here
  3001. .comment
  3002. PORTABLE TEXT FORMATTER (PTF)
  3003. .. .sp
  3004. .. OF
  3005. .. .sp
  3006. .comment
  3007. .! The name of the system appears here
  3008. .comment
  3009. .. [SYSTEM NAME]
  3010.  
  3011. .spaceto -20
  3012. .comment
  3013. .! The contract number and other information appear here
  3014. .comment
  3015. CONTRACT NO. <None>
  3016. .sp
  3017. CDRL SEQUENCE NO. <None>
  3018. .sp 2
  3019. Prepared for:
  3020. .sp
  3021. Ada Software Repository
  3022. Host Computer WSMR-SIMTEL20.ARMY.MIL
  3023. White Sands Missile Range, New Mexico
  3024. .sp 2
  3025. Prepared by:
  3026. .sp
  3027. Richard Conn
  3028.  
  3029. .ce off
  3030.  
  3031. .comment
  3032. .! The next page starts with the Scope and is numbered 1.
  3033. .! The table of contents is created at the end of the PTF
  3034. .! output file and should be inserted after this title page.
  3035. .comment
  3036. .bp 1
  3037. .fo //#//
  3038. .cl
  3039. .SECT 0 1. Scope
  3040. .SECT 1 1.1 Identification
  3041. .PP
  3042. This document is the Version Description Document for the
  3043. .ul
  3044. Portable Text Formatter
  3045. (PTF), Version 1.2.  This document applies to the PTF as it operates on
  3046. any hardware platform to which a validated Ada compiler targets.
  3047. .SECT 1 1.2 System overview
  3048. .include ptfover.ptf
  3049. .SECT 1 1.3 Documentation overview
  3050. .PP
  3051. This purpose of this document is to define the files associated with
  3052. the Version 1.2 release of PTF and to instruct the reader in the procedure
  3053. for compiling the Ada source code of PTF.
  3054. .bp
  3055. .cl
  3056. .SECT 0 2. Referenced documents
  3057. .PP
  3058. Richard Conn,
  3059. .ul
  3060. PTF 1.2 Software User's Manual,
  3061. 7 May 1990.  This manual is a part of the distribution of PTF 1.2
  3062. and can be found in the Ada Software Repository.
  3063. .bp
  3064. .cl
  3065. .SECT 0 3. Version description
  3066. .SECT 1 3.1 Inventory of materials released
  3067. .PP
  3068. The following files comprise the release of this CSCI:
  3069. .sp
  3070. .nf
  3071. .li +5
  3072. .ul
  3073. Filename      Comments
  3074. cli2.src      Command line interfaces
  3075. ptfread.me    Short READ.ME file
  3076. ptfspec.src   PTF package specifications
  3077. ptfbody.src   PTF package bodies
  3078. ptfmain.src   PTF and PTFIDX mainlines
  3079. ptfdocs.src   PTF documentation (raw form)
  3080. ptftest.src   PTF unit test programs
  3081. ptf.sum       PTF Software User's Manual
  3082. ptfindex.sum  Index to PTF Software User's Manual
  3083. ptf.sdd       PTF Software Design Document
  3084. ptf.vdd       PTF Version Description Document
  3085. ptf.exe       Executable of Ptf for MSDOS Systems*
  3086. ptfidx.exe    Executable of Ptf for MSDOS Systems*
  3087. ptf.zip       ZIP file containing all of the above*
  3088. .li -5
  3089. .fi
  3090. .PP
  3091. *The *.EXE and *.ZIP files are in the MSDOS archives only.
  3092. All other files are in both the Ada Software Repository.
  3093. .PP
  3094. CLI2.SRC contains a command line interface package specification and
  3095. various package bodies for various target environments.
  3096. .PP
  3097. PTFSPEC.SRC contains the specifications of the various packages and
  3098. stand-alone procedures which make up PTF.  These specifications are
  3099. stored in compilation order.
  3100. .PP
  3101. PTFBODY.SRC contains the
  3102. bodies of the various packages which make up PTF.  These bodies are stored
  3103. in compilation order.
  3104. .PP
  3105. PTFMAIN.SRC contains the source to the mainline procedures Ptf and Ptfidx.
  3106. Compile this file after compiling the appropriate CLI files, PTFSPEC.SRC,
  3107. and PTFBODY.SRC.
  3108. .PP
  3109. PTFDOCS.SRC contains the *.PTF files which make up the
  3110. .ul
  3111. Software User's Manual,
  3112. the
  3113. .ul
  3114. Software Design Document,
  3115. the
  3116. .ul
  3117. Version Description Document,
  3118. and the Problem/Change Reports
  3119. for PTF (these files must be processed by PTF).
  3120. .PP
  3121. PTFTEST.SRC contains unit test programs for many of the component
  3122. packages and procedures within PTF.  PTFSPEC.SRC and PTFBODY.SRC
  3123. should be compiled before compiling the test programs in PTFTEST.SRC.
  3124. .sp
  3125. .SECT 1 3.2 Inventory of CSCI contents
  3126. .PP
  3127. The following is an alphabetical listing of the individual
  3128. software component files which comprise the PTF CSCI.  These component
  3129. files are contained within the delivered files CLI2.SRC,
  3130. PTFSPEC.SRC, and PTFBODY.SRC.
  3131. .li +5
  3132. .sp
  3133. .nf
  3134. .ul
  3135. In CLI2.SRC (this may change as CLI2 is updated):
  3136. .sp
  3137. .ec \
  3138. .ul
  3139. Filename           Comments
  3140. cli.ada            CLI reused from ASR
  3141. clialsys.ada       for Alsys Ada
  3142. clicais.ada        for CAIS interface
  3143. cligenrl.ada       for anything else
  3144. cliintgr.ada       for IntegrAda (Janus Ada)
  3145. climerdn.ada       for Meridian Ada
  3146. cliverdx.ada       for Verdix Ada
  3147. clivms.ada         for DEC Ada
  3148. .sp 2
  3149. .ul
  3150. In PTFSPEC.SRC and PTFBODY.SRC:
  3151. .sp
  3152. .ul
  3153. Filename           Comments
  3154. clp.a              Reused from ASR
  3155. clp_body.a         Reused from ASR
  3156. cmd.a
  3157. cmd_body.a
  3158. cmd_sym.a
  3159. cnt.a
  3160. cnt_body.a
  3161. cot.a
  3162. cot_body.a
  3163. dyn.a              Reused from ASR
  3164. env.a
  3165. env_body.a
  3166. err.a
  3167. err_body.a
  3168. fof.a
  3169. fof_body.a
  3170. idx.a
  3171. idx_body.a
  3172. in.a
  3173. in_body.a
  3174. mac.a
  3175. mac_body.a
  3176. out.a
  3177. out_body.a
  3178. parse.a
  3179. sort.a             Reused from ASR
  3180. var.a
  3181. var_body.a
  3182. wp.a
  3183. wp_body.a
  3184. .sp 2
  3185. .ul
  3186. In PTFMAIN.SRC:
  3187. .sp
  3188. .ul
  3189. Filename           Comments
  3190. ptf.a              PTF mainline procedure
  3191. ptfidx.a           PTFIDX mainline procedure
  3192. .sp 2
  3193. .ul
  3194. In PTFDOCS.SRC:
  3195. .sp
  3196. .ul
  3197. Filename           Comments
  3198. ptfsum.ptf         Software User's Manual
  3199. ptfsumid.ptf       Index for Software User's Manual
  3200. ptfvdd.ptf         Version Description Document
  3201. ptfsdd.ptf         Software Design Document
  3202. ptfacr.ptf         Acronym list
  3203. ptfover.ptf        Overview
  3204. zzz2167a.ptf       General-purpose macros
  3205. ptfpcr01.ptf       Problem/Change Report 1
  3206. ptfpcr02.ptf       Problem/Change Report 2
  3207. ptfpcr03.ptf       Problem/Change Report 3
  3208. ptfpcr04.ptf       Problem/Change Report 4
  3209. ptfpcr05.ptf       Problem/Change Report 5
  3210. ptfpcr06.ptf       Problem/Change Report 6
  3211. .sp 2
  3212. .ul
  3213. In PTFTEST.SRC:
  3214. .sp
  3215. .ul
  3216. Filename           Comments
  3217. err_test.a         Test Error_Log
  3218. foftest1.a         Test Formatted_Output_File
  3219. foftest2.a         "
  3220. foftest3.a         "
  3221. foftest4.a         "
  3222. mac_test.a         Test Macro
  3223. parsetst.a         Test Parse
  3224. var_test.a         Test Variable
  3225. wp_test.a          Test Word_Processor
  3226. foftest2.inp       Data file for FOFTEST2.A
  3227. wptest1.in         Data file for WP_TEST.A
  3228. wptest2.in         "
  3229. wptest2a.in        "
  3230. wptest2b.in        "
  3231. wptest3.in         "
  3232. wptest4.in         "
  3233. wptest5.in         "
  3234. wptest6.in         "
  3235. .li -5
  3236. .fi
  3237. .SECT 1 3.3 Class I changes installed
  3238. .PP
  3239. PTF-05 documents a Priority 1 change installed in this release.
  3240. .SECT 1 3.4 Class II changes installed
  3241. .PP
  3242. No Priority 2 changes have been installed.  All other changes, in
  3243. PTF-01 to PTF-04 and PTF-06 are Priority 4 changes.
  3244. .SECT 1 3.5 Adaptation data
  3245. .PP
  3246. The package CLI (Command Line Interface) contains the only system-dependent
  3247. information.  The file CLI2.SRC contains the package specification of CLI
  3248. and several different package bodies, each unique for a particular
  3249. installation.  The file CLIGENRL.ADA in CLI2.SRC is a general-purpose
  3250. body which should be used if no other body is applicable.
  3251. .PP
  3252. The file CLI2.SRC in PD2:<ADA.COMPONENTS> in the Ada Software Repository
  3253. is the most current version of this package.  Users of the ASR should
  3254. keep up to date with improvements on this package as they come out if
  3255. the version of this package in the distribution does not meet the needs
  3256. of the user.
  3257. .SECT 1 3.6 Interface compatibility
  3258. .PP
  3259. The interface to this revision of PTF is compatible with previous interfaces.
  3260. Some new command line options have been added.
  3261. .SECT 1 3.7 Bibliography of reference documents
  3262. .PP
  3263. Documents prepared by Richard Conn for this release of PTF:
  3264. .li +5
  3265. .LIST 4
  3266. .LE PTF 1.2 Software Design Document
  3267. .LE PTF 1.2 Software User's Manual
  3268. .LE PTF 1.2 Version Description Document
  3269. .ELIST
  3270. .li -5
  3271. .SECT 1 3.8 Summary of change
  3272. .PP
  3273. This Version Description Document (VDD) covers the following
  3274. Problem/Change Reports:
  3275. .sp
  3276. .li +10
  3277. .nf
  3278. .ul
  3279. Report ID        File Name
  3280. PTF-01           ptfpcr01.ptf
  3281. PTF-02           ptfpcr02.ptf
  3282. PTF-03           ptfpcr03.ptf
  3283. PTF-04           ptfpcr04.ptf
  3284. PTF-05           ptfpcr05.ptf
  3285. PTF-06           ptfpcr06.ptf
  3286. .fi
  3287. .li -10
  3288. .PP
  3289. See PTF-01 to PTF-06 for details on the changes incorporated into this
  3290. revision.
  3291. .SECT 1 3.9 Installation instructions
  3292. .PP
  3293. The installation of the PTF System amounts to compiling the two programs,
  3294. Ptf and Ptfidx, and placing both of these in an area of the target system
  3295. which can be accessed by the users.
  3296. .PP
  3297. To compile Ptf and Ptfidx, take the following steps.  Note that the file names
  3298. of these file may be changed in order to perform the Ada compilations
  3299. (e.g., Verdix Ada requires that all Ada source files end in ".a").
  3300. .li +5
  3301. .LIST 4
  3302. .LE Set up a Working Directory
  3303. .PP
  3304. This directory should contain the following at a minimum:
  3305. .li +5
  3306. .SLIST 4
  3307. .SLE Contents of CLI2.SRC as separate files
  3308. .SLE PTFSPEC.SRC
  3309. .SLE PTFBODY.SRC
  3310. .SLE PTFMAIN.SRC
  3311. .ESLIST
  3312. .li -5
  3313. .LE Create an Ada Program Unit Library.
  3314. .PP
  3315. Virtually all Ada compilers require that this be done first.
  3316. .LE Compile CLI.ADA
  3317. .PP
  3318. This is the specification to the package Cli, which is contained
  3319. in the file CLI2.SRC.
  3320. .LE Compile the appropriate body of CLI
  3321. .PP
  3322. Select the package body appropriate for your target and compile it.
  3323. Instructions are included in the file CLI2.SRC.
  3324. .LE Compile PTFSPEC.SRC
  3325. .PP
  3326. This file contains all of the package specifications and stand-alone
  3327. subprograms in compilation order.  These component files, in compilation
  3328. order, are:
  3329. .sp
  3330. .li +5
  3331. .nf
  3332. .na
  3333. clp.a
  3334. dyn.a
  3335. sort.a
  3336. cot.a
  3337. in.a
  3338. out.a
  3339. cmd_sym.a
  3340. err.a
  3341. idx.a
  3342. var.a
  3343. parse.a
  3344. fof.a
  3345. cnt.a
  3346. env.a
  3347. mac.a
  3348. cmd.a
  3349. wp.a
  3350. .ap
  3351. .fi
  3352. .li -5
  3353. .PP
  3354. If your Ada compiler does not have the capacity to compile a file as large
  3355. as PTFSPEC.SRC, it will be necessary to extract the component files
  3356. (the PAGER2 tool in the Ada Software Repository or a text editor can do this)
  3357. and compile them individually.
  3358. .LE Compile PTFBODY.SRC
  3359. .PP
  3360. This file contains all of the package bodies in compilation order.
  3361. These component files, in compilation order, are:
  3362. .sp
  3363. .li +5
  3364. .nf
  3365. .na
  3366. clp_body.a
  3367. cmd_body.a
  3368. cnt_body.a
  3369. cot_body.a
  3370. env_body.a
  3371. err_body.a
  3372. fof_body.a
  3373. idx_body.a
  3374. in_body.a
  3375. mac_body.a
  3376. out_body.a
  3377. var_body.a
  3378. wp_body.a
  3379. .ap
  3380. .fi
  3381. .li -5
  3382. .PP
  3383. If your Ada compiler does not have the capacity to compile a file as large
  3384. as PTFBODY.SRC, it will be necessary to extract the component files
  3385. (the PAGER2 tool in the Ada Software Repository or a text editor can do this)
  3386. and compile them individually.
  3387. .LE Compile PTFMAIN.SRC
  3388. .PP
  3389. This file contains PTF.A and PTFIDX.A, the two mainline procedures.
  3390. .LE Bind Ptf and Ptfidx
  3391. .PP
  3392. This will create the executables Ptf and Ptfidx.  The names of the mainline
  3393. procedures are "Ptf" and "Ptfidx."
  3394. .ELIST
  3395. .li -5
  3396. .SECT 1 3.10 Possible problems and known errors
  3397. .PP
  3398. There are no known problems or errors with this CSCI.
  3399. .bp
  3400. .cl
  3401. .SECT 0 4. Notes
  3402. .SECT 1 4.1 Acronyms
  3403. .include ptfacr.ptf
  3404. .bp 1
  3405. .pn arabic A-#
  3406. .cl
  3407. .SECT 0 A Sample Compilation/Binding Command Sequences
  3408. .SECT 1 A.1 Janus/Ada or IntegrAda (IBM PC clone platform)
  3409. .PP
  3410. The distribution of PTF in the ARC file contains two EXE files, PTF.EXE
  3411. and PTFIDX.EXE.  These files are ready to run on an IBM PC clone
  3412. without any further effort.  The following instructions are provided for
  3413. those who wish to produce these EXE files themselves by compiling the
  3414. source code.
  3415. .SECT 2 A.1.1 Create a program unit library
  3416. .PP
  3417. This step is not necessary for Janus/Ada or IntegrAda.
  3418. .SECT 2 A.1.2 Compile CLI.ADA
  3419. .sp
  3420. .nf
  3421. compile cli.ada /o1 /d /t /z
  3422. .fi
  3423. .SECT 2 A.1.3 Compile the appropriate CLI body
  3424. .sp
  3425. .nf
  3426. compile cliintgr.ada /o1 /d /t /z
  3427. .fi
  3428. .SECT 2 A.1.4 Compile PTFSPEC.SRC
  3429. .sp
  3430. .nf
  3431. compile ptfspec.src /o1 /d /t /z
  3432. .fi
  3433. .SECT 2 A.1.5 Compile PTFBODY.SRC
  3434. .PP
  3435. PTFBODY.SRC is too large for this compiler to handle as a single file.
  3436. It must be broken into its components (by using the PAGER2 tool in the
  3437. Ada Software Repository or a text editor), and the component files must
  3438. be compiled separately.  Also, since these are all package bodies, the
  3439. compilation order is not important (it is presented alphabetically below).
  3440. .sp
  3441. .nf
  3442. compile clp_body.a /o1 /d /t /z
  3443. compile cmd_body.a /o1 /d /t /z
  3444. compile cnt_body.a /o1 /d /t /z
  3445. compile cot_body.a /o1 /d /t /z
  3446. compile env_body.a /o1 /d /t /z
  3447. compile err_body.a /o1 /d /t /z
  3448. compile fof_body.a /o1 /d /t /z
  3449. compile idx_body.a /o1 /d /t /z
  3450. compile in_body.a /o1 /d /t /z
  3451. compile mac_body.a /o1 /d /t /z
  3452. compile out_body.a /o1 /d /t /z
  3453. compile var_body.a /o1 /d /t /z
  3454. compile wp_body.a /o1 /d /t /z
  3455. .fi
  3456. .SECT 2 A.1.6 Compile PTFMAIN.SRC
  3457. .sp
  3458. .nf
  3459. compile ptfmain.src /o1 /d /t /z
  3460. .fi
  3461. .SECT 2 A.1.7 Bind Ptf and Ptfidx
  3462. .sp
  3463. .nf
  3464. bind ptf /o1 /t
  3465. bind ptfidx /o1 /t
  3466. .fi
  3467. .SECT 1 A.2 Verdix Ada (Sun workstation platform)
  3468. .PP
  3469. The main thing to note below is that all file names of those files to
  3470. be compiled must end in a ".a".
  3471. .SECT 2 A.2.1 Create a program unit library
  3472. .sp
  3473. .nf
  3474. a.mklib -i
  3475. << select the desired Ada compiler >>
  3476. .fi
  3477. .SECT 2 A.2.2 Compile CLI.ADA
  3478. .sp
  3479. .nf
  3480. mv cli.ada cli.a
  3481. ada cli.a
  3482. .fi
  3483. .SECT 2 A.2.3 Compile the appropriate CLI body
  3484. .sp
  3485. .nf
  3486. mv cliverdx.ada cliverdx.a
  3487. ada cliverdx.a
  3488. .fi
  3489. .SECT 2 A.2.4 Compile PTFSPEC.SRC
  3490. .sp
  3491. .nf
  3492. mv ptfspec.src ptfspec.a
  3493. ada ptfspec.a
  3494. .fi
  3495. .SECT 2 A.2.5 Compile PTFBODY.SRC
  3496. .sp
  3497. .nf
  3498. mv ptfbody.src ptfbody.a
  3499. ada ptfbody.a
  3500. .fi
  3501. .SECT 2 A.2.6 Compile PTFMAIN.SRC
  3502. .sp
  3503. .nf
  3504. mv ptfmain.src ptfmain.a
  3505. ada ptfmain.a
  3506. .fi
  3507. .SECT 2 A.2.7 Bind Ptf and Ptfidx
  3508. .sp
  3509. .nf
  3510. a.ld -o ptf ptf
  3511. a.ld -o ptfidx ptfidx
  3512. .fi
  3513. .SECT 1 A.3 DEC Ada (VAX/VMS platform)
  3514. .SECT 2 A.3.1 Create a program unit library
  3515. .PP
  3516. These steps create a subdirectory called [.LIB] as the program unit library.
  3517. .sp
  3518. .nf
  3519. acs cre lib [.lib]
  3520. acs set lib [.lib]
  3521. .fi
  3522. .SECT 2 A.3.2 Compile CLI.ADA
  3523. .sp
  3524. .nf
  3525. ada cli.ada
  3526. .fi
  3527. .SECT 2 A.3.3 Compile the appropriate CLI body
  3528. .sp
  3529. .nf
  3530. ada clivms.ada
  3531. .fi
  3532. .SECT 2 A.3.4 Compile PTFSPEC.SRC
  3533. .sp
  3534. .nf
  3535. ada ptfspec.src
  3536. .fi
  3537. .SECT 2 A.3.5 Compile PTFBODY.SRC
  3538. .sp
  3539. .nf
  3540. ada ptfbody.src
  3541. .fi
  3542. .SECT 2 A.3.6 Compile PTFMAIN.SRC
  3543. .sp
  3544. .nf
  3545. ada ptfmain.src
  3546. .fi
  3547. .SECT 2 A.3.7 Bind Ptf and Ptfidx
  3548. .sp
  3549. .nf
  3550. acs link ptf
  3551. acs link ptfidx
  3552. .fi
  3553. .PP
  3554. At this point, the current directory contains the executable files PTF.EXE
  3555. and PTFIDX.EXE.  To run these programs, symbols must be defined during
  3556. each session before the programs are executed.  The user should put
  3557. commands like the following into his LOGIN.COM file:
  3558. .sp
  3559. .nf
  3560. ptf:==$disk:[dir.subdir]ptf
  3561. ptfidx:==$disk:[dir.subdir]ptfidx
  3562. .fi
  3563. .PP
  3564. In the example above, "disk:[dir.subdir]" names the disk and directory
  3565. (with subdirectory if needed) in which the files PTF.EXE and PTFIDX.EXE
  3566. reside.
  3567. .bp
  3568. .sp 20
  3569. .ce
  3570. This Page Intentionally Blank
  3571. .bp 1
  3572. .pn arabic B-#
  3573. .cl
  3574. .SECT 0 B Building the PTF Documents
  3575. .PP
  3576. This appendix shows the PTF System commands used to build the files
  3577. PTF.SUM, PTFINDEX.SUM, PTF.SDD, and PTF.VDD.
  3578. .SECT 1 B.1 Building PTF.SUM and PTFINDEX.SUM
  3579. .PP
  3580. To build PTF.SUM and PTFINDEX.SUM, the following commands were issued:
  3581. .li +5
  3582. .LIST 4
  3583. .LE ptf ptfsum.ptf ptf.sum
  3584. .LE ptfidx
  3585. .LE emacs ptfidx.ptf
  3586. .LE ptf ptfsumid.ptf ptfindex.sum
  3587. .LE rm ptfidx.ptf
  3588. .ELIST
  3589. .li -5
  3590. .PP
  3591. The "emacs" command was used to edit the file "ptfidx.ptf" because some
  3592. of the index entries contained dot commands.  While in the editor,
  3593. ".cc \" and "\cc" commands were place around (before and after)
  3594. that part of the index.
  3595. .PP
  3596. The "rm" command deletes the remaining "ptfidx.ptf" file.
  3597. .SECT 1 B.2 Building PTF.SDD
  3598. .PP
  3599. The following command was issued to build the file "ptf.sdd":
  3600. .sp
  3601. .ce
  3602. ptf ptfsdd.ptf ptf.sdd
  3603. .SECT 1 B.3 Building PTF.VDD
  3604. .PP
  3605. The following command was issued to build the file "ptf.vdd":
  3606. .sp
  3607. .ce
  3608. ptf ptfvdd.ptf ptf.vdd
  3609. .bp
  3610. .sp 20
  3611. .ce
  3612. This Page Intentionally Blank
  3613. .comment
  3614. .! The table of contents is automatically generated and placed
  3615. .! here in the document file.  It should be physically moved to
  3616. .! after the title page after printing the document.
  3617. .comment
  3618. .bp 2
  3619. .pn lower_roman #
  3620. .ce
  3621. .ul
  3622. Table of Contents
  3623. .sp 2
  3624. .pc
  3625. .comment
  3626. .! This is provided in case the table of contents ends on an odd
  3627. .! page number.
  3628. .comment
  3629. .bp
  3630. .sp 20
  3631. .ce
  3632. This page intentionally blank
  3633. --::::::::::
  3634. --ptfsdd.ptf
  3635. --::::::::::
  3636. .comment
  3637. .! Software Design Document (2167A, DI-MCCR-80012A) for:
  3638. .!   Portable Text Formatter (PTF)
  3639. .! Prepared by:  Richard Conn
  3640. .! Date:        2/27/90
  3641. .! Modifications
  3642. .! 08/24/89  1.0  Rick Conn  Initial Version
  3643. .! 02/27/90  1.1  Rick Conn  PTFPCR-1 to PTFPCR-4 Fixes
  3644. .! 05/07/90  1.2  Rick Conn  PTFPCR-5 and PTFPCR-6 Fixes
  3645. .!
  3646. .! Description and Purpose:
  3647. .!   1. The Software Design Document (SDD) describes the complete design
  3648. .! of a Computer Software Configuration Item (CSCI).  It describes the
  3649. .! CSCI as composed of Computer Software Components (CSCs) and Computer
  3650. .! Software Units (CSUs).
  3651. .!   2. The SDD describes the allocation of requirements from a CSCI to its
  3652. .! CSCs and CSUs.  Prior to Preliminary Design Review, the SDD is entered
  3653. .! into the Developmental Configuration for the CSCI.  Upon completion of
  3654. .! Physical Configuration Audit (PCA), the SDD, as part of the Software
  3655. .! Product Specification, is entered into the Product Baseline for the CSCI.
  3656. .!   3. The SDD is used by the contractor for three primary purposes, namely:
  3657. .! (1) present the preliminary design at the Preliminary Design Review(s),
  3658. .! (2) present the detailed design at the Critical Design Review(s), and
  3659. .! (3) use the design information as the basis for coding each CSU.
  3660. .!   4. The SDD is used by the Government to assess the preliminary and
  3661. .! detailed design of a CSCI.
  3662. .!
  3663. .! <<<< This PTF template is not stand-alone; refer to the DID >>>>
  3664. .!
  3665. .! Tailoring Instructions:
  3666. .!    To tailor this template, fill in the areas surrounded by
  3667. .! [] as indicated.
  3668. .comment
  3669.  
  3670. .comment
  3671. .! These are global variables used in the document.
  3672. .comment
  3673. .vs IDXFILE ptf.idx
  3674. .vs PTFIDXFILE ptfidx.ptf
  3675. .vs TMPFILE ptfidx.tmp
  3676. .comment
  3677. .! This is set for PICA type (10 chars/inch).  Change accordingly
  3678. .! for ELITE or other type styles.  Also, the default top and bottom
  3679. .! margins and headers are used, giving 1 inch top and bottom for
  3680. .! both margins and headers at 6 lines/inch.  No auto-paragraphing.
  3681. .comment
  3682. .lm 11
  3683. .rm 70
  3684.  
  3685. .comment
  3686. .! The following reads in a set of macros used by all the 2167A
  3687. .! document templates.
  3688. .comment
  3689. .include zzz2167a.ptf
  3690.  
  3691. .comment
  3692. .! Set the page heading to contain the Document Control
  3693. .! Number and date.  The Document Control Number contains
  3694. .! revision and volume identification as applicable.
  3695. .comment
  3696. .he //PTF 1.2 Software Design Document//
  3697.  
  3698. .ce on
  3699.  
  3700. .comment
  3701. .! The next line contains the revision indicator and the
  3702. .! date of revision.
  3703. .comment
  3704.  
  3705. Version 1.2: 7 May 1990
  3706.  
  3707. .spaceto +15
  3708. SOFTWARE DESIGN DOCUMENT
  3709. .sp
  3710. FOR THE
  3711. .sp
  3712. .comment
  3713. .! The name of the CSCI appears here
  3714. .comment
  3715. PORTABLE TEXT FORMATTER (PTF)
  3716. .. .sp
  3717. .. OF
  3718. .. .sp
  3719. .comment
  3720. .! The name of the system appears here
  3721. .comment
  3722. .. [SYSTEM NAME]
  3723.  
  3724. .spaceto -20
  3725. .comment
  3726. .! The contract number and other information appear here
  3727. .comment
  3728. CONTRACT NO. <None>
  3729. .sp
  3730. CDRL SEQUENCE NO. <None>
  3731. .sp 2
  3732. Prepared for:
  3733. .sp
  3734. Ada Software Repository
  3735. Host Computer WSMR-SIMTEL20.ARMY.MIL
  3736. White Sands Missile Range, New Mexico
  3737. .sp 2
  3738. Prepared by:
  3739. .sp
  3740. Richard Conn
  3741.  
  3742. .ce off
  3743. .comment
  3744. .! The following sets the escape character from an underscore
  3745. .! (default) to a backslash.  This is to remove the need to
  3746. .! double all underscores within file names.
  3747. .comment
  3748. .ec \
  3749.  
  3750. .comment
  3751. .! The next page starts with the Scope and is numbered 1.
  3752. .! The table of contents is created at the end of the PTF
  3753. .! output file and should be inserted after this title page.
  3754. .comment
  3755. .bp 1
  3756. .fo //#//
  3757. .cl
  3758. .SECT 0 1. Scope
  3759. .SECT 1 1.1 Identification
  3760. .PP
  3761. This document is the Software Design Document for the
  3762. .ul
  3763. Portable Text Formatter
  3764. (PTF), Version 1.2.  This document applies to the PTF as it
  3765. operates on any hardware platform to which a validated Ada compiler
  3766. targets.
  3767. .SECT 1 1.2 System overview
  3768. .include ptfover.ptf
  3769. .SECT 1 1.3 Documentation overview
  3770. .PP
  3771. The purpose of this document is to outline the design of the
  3772. .ul
  3773. Portable Text Formatter
  3774. (PTF) in order to support its maintenance.  Only the overall design
  3775. is discussed, and a detailed design is not presented.  The reader is
  3776. referred to the source code of PTF, using the overall design information
  3777. in this document as a guide.
  3778. .bp
  3779. .cl
  3780. .SECT 0 2. Referenced documents
  3781. .PP
  3782. Richard Conn,
  3783. .ul
  3784. PTF 1.2 Software User's Manual,
  3785. 7 May 1990.  This manual is a part of the distribution of PTF 1.2
  3786. and can be found in the Ada Software Repository.
  3787. .PP
  3788. Ozan S. Yigit and Steven Tress,
  3789. .ul
  3790. PROFF User's Guide Version 1.0,
  3791. March 1984, SIMTEL20 archives.
  3792. .bp
  3793. .cl
  3794. .SECT 0 3. Preliminary design.
  3795. .PP
  3796. The PTF System is an object-oriented design written in Ada which
  3797. is composed of two related programs: the Portable Text Formatter (PTF)
  3798. and the Portable Text Formatter Indexer (PTFIDX).  These top-level
  3799. objects are
  3800. further supported by the following interacting subordinate objects:
  3801. .li +5
  3802. .LIST 4
  3803. .LE Command_Line_Interface*
  3804. .LE Command_Line_Processor*
  3805. .LE Dynamic_String*
  3806. .LE Console
  3807. .LE Input_File
  3808. .LE Output_File
  3809. .LE Command_Symbols
  3810. .LE Error_Log
  3811. .LE Index
  3812. .LE Variable
  3813. .LE Formatted_Output_File
  3814. .LE Contents
  3815. .LE Environment
  3816. .LE Macros
  3817. .LE Command
  3818. .LE Word_Processor
  3819. .ELIST
  3820. .li -5
  3821. .PP
  3822. The following functions are also provided for general-purpose support:
  3823. .li +5
  3824. .LIST 4
  3825. .LE Parse
  3826. .LE Sort*
  3827. .ELIST
  3828. .li -5
  3829. .PP
  3830. The items marked with an asterisk (*) in the above lists were reused from
  3831. code available in the Ada Software Repository.
  3832. .SECT 1 3.1. CSCI overview.
  3833. .PP
  3834. The Portable Text Formatter program reads options, the names of input files,
  3835. the names of include files (which, in turn, contain the names of input files
  3836. and other include files), and the name of an output file from the command
  3837. line.  It passes the name of the output file on to the Word_Processor object
  3838. followed by the names of each of the input files (including those referenced
  3839. by the include files) as they were encountered in the Command_Line_Interface
  3840. and the include files.  The output file, as a formatted
  3841. document, and an optional index file named
  3842. "@IDXFILE" are created by the Portable Text Formatter.
  3843. .PP
  3844. If any commands to create index entries are present in any of the input files,
  3845. the "@IDXFILE" file is created.  This file is read by the Portable Text
  3846. Formatter Indexer, which creates the file "@PTFIDXFILE" for final processing
  3847. by the Portable Text Formatter to create the index pages for the output file.
  3848. .SECT 2 3.1.1. CSCI architecture.
  3849. .SECT 3 3.1.1.1 Portable Text Formatter
  3850. .PP
  3851. The Portable Text Formatter is implemented as a procedure named "Ptf."
  3852. Ptf is composed of the following packages and subprograms:
  3853. .li +5
  3854. .LIST 4
  3855. .LE File_List
  3856. .LE Help_Message
  3857. .LE Is_File
  3858. .LE File_Count
  3859. .LE Process_Options
  3860. .LE Open_Output_File
  3861. .LE the mainline of Ptf
  3862. .ELIST
  3863. .li -5
  3864. .SECT 4 3.1.1.1.1 Objects referenced
  3865. .PP
  3866. Ptf interfaces with the following objects and functional entities.
  3867. .li +5
  3868. .LIST 4
  3869. .LE Command_Symbols
  3870. .LE Console
  3871. .LE Error_Log
  3872. .LE Index
  3873. .LE Output_File
  3874. .LE Variable
  3875. .LE Word_Processor
  3876. .ELIST
  3877. .li -5
  3878. .SECT 4 3.1.1.1.2 Non-developmental software
  3879. .PP
  3880. PTF interfaces with the following non-developmental objects and
  3881. functional entities.
  3882. They were acquired from the Ada Software Repository.
  3883. .li +5
  3884. .LIST 4
  3885. .LE Command_Line_Interface
  3886. .LE Command_Line_Processor
  3887. .ELIST
  3888. .li -5
  3889. .SECT 3 3.1.1.2 Portable Text Formatter Indexer
  3890. .PP
  3891. The Portable Text Formatter Index is implemented as a procedure named
  3892. "Ptfidx."  Ptfidx is composed of the following packages and subprograms:
  3893. .li +5
  3894. .LIST 4
  3895. .LE Help_Message
  3896. .LE Is_File
  3897. .LE Process_Options
  3898. .LE To_Nat
  3899. .LE To_Lower
  3900. .LE To_Upper (two versions)
  3901. .LE Pass1
  3902. .LE Pass2
  3903. .LE Pass3
  3904. .LE the mainline of Ptfidx
  3905. .ELIST
  3906. .li -5
  3907. .SECT 4 3.1.1.2.1 Objects referenced
  3908. .PP
  3909. Ptfidx interfaces with the following objects and functional entities.
  3910. .li +5
  3911. .LIST 4
  3912. .LE Command_Symbols
  3913. .LE Console
  3914. .LE Error_Log
  3915. .LE Input_File
  3916. .LE Output_File
  3917. .LE Sort
  3918. .LE Variable
  3919. .ELIST
  3920. .li -5
  3921. .SECT 4 3.1.1.2.2 Non-developmental software
  3922. .PP
  3923. Ptfidx interfaces with the following non-developmental objects and
  3924. functional entities.  
  3925. They were acquired from the Ada Software Repository.
  3926. .li +5
  3927. .LIST 4
  3928. .LE Command_Line_Interface
  3929. .ELIST
  3930. .li -5
  3931. .SECT 2 3.1.2. System states and modes.
  3932. .SECT 3 3.1.2.1 Portable Text Formatter
  3933. .PP
  3934. Ptf transitions through the following states during its operation.
  3935. .li +2
  3936. .LIST 4
  3937. .LE Initialization
  3938. .PP
  3939. The Error_Log is opened to standard output (the Console), the file name
  3940. and line number variables are initialized, the signon message is output to
  3941. the Console, and the Command_Line_Interface is initialized.
  3942. .LE Process Command Line Options
  3943. .PP
  3944. Each token in the command line is examined for a leading dash (-), and,
  3945. if one is found, it is processed as an option.
  3946. .LE Further Initialization
  3947. .PP
  3948. If the help message was not displayed during the processing of the
  3949. command line options, then the error log file is opened (if error logging
  3950. was requested by a command line option) and the list of files to process
  3951. is initialized.
  3952. .LE Blank Help Display
  3953. .PP
  3954. If there were no arguments on the command line, the help message is
  3955. displayed.
  3956. .LE Main Processing Activity
  3957. .PP
  3958. If the help message was not requested, if all options were valid, and
  3959. if two or more files were specified in the command line (an input file
  3960. and an output file, as a minimum), then the main processing activity begins.
  3961. .SLIST 4
  3962. .SLE Open the output file
  3963. .PP
  3964. If the output file is opened successfully, the Main Processing Activity
  3965. continues.
  3966. .SLE Write the name of the output file to the console.
  3967. .SLE Loop through the tokens provided by the Command_Line_Interface.
  3968. .PP
  3969. For each file name token (which does not begin with a dash), add it
  3970. to the file list.  Include files, which begin with an ampersand (\@),
  3971. are processed.
  3972. .SLE Process each input file
  3973. .PP
  3974. Loop through the list of files created by the previous step, passing
  3975. their names to the Word_Processor.
  3976. .SLE Close the output file of the Word_Processor.
  3977. .ESLIST
  3978. .LE Close the Error_Log and Index
  3979. .ELIST
  3980. .li -2
  3981. .SECT 3 3.1.2.2 Portable Text Formatter Indexer
  3982. .PP
  3983. Ptfidx transitions through the following states during its operation.
  3984. .li +2
  3985. .LIST 4
  3986. .LE Initialization
  3987. .PP
  3988. The Error_Log is opened to standard output (the Console), the file name
  3989. and line number are initialized, the signon message is displayed at the
  3990. Console, and the Command_Line_Interface is initialized.
  3991. .LE Process Command Line Options
  3992. .PP
  3993. Each token in the command line is examined and processed as an option
  3994. if it begins with a dash (-).  The only option recognized by
  3995. Ptfidx is the help message request.
  3996. .LE Main Processing Activity
  3997. .PP
  3998. If the help message was not requested, the Main Processing Activity begins.
  3999. .SLIST 4
  4000. .SLE Pass1
  4001. .PP
  4002. Pass1 is the initial processing on the "@IDXFILE" file.
  4003. It determines the values of Total_Line_Length, Index_Length, and
  4004. Element_Count (internal variables) and creates the "@TMPFILE" (which
  4005. contains the "@IDXFILE" with the duplicate entries removed).
  4006. .SLE Pass2
  4007. .PP
  4008. Pass2 reads in the index entries from the "@TMPFILE" file, sorts them,
  4009. and builds a new "@TMPFILE" as its output.  It deletes the first
  4010. version of "@TMPFILE" and creates a new version, suitable for use by Pass3.
  4011. .SLE Pass3
  4012. .PP
  4013. Pass3 reads in the single
  4014. column of index entries from "@TMPFILE" and generates the dual-column
  4015. output file "@PTFIDXFILE."  "@TMPFILE" is deleted.
  4016. .SLE Delete the input file "@IDXFILE"
  4017. .SLE Display the "processing complete" message
  4018. .ESLIST
  4019. .LE Close the Error_Log
  4020. .ELIST
  4021. .li -2
  4022. .SECT 2 3.1.3. Memory and processing time allocation.
  4023. .PP
  4024. This data is not significant for the successful operation of the tool and
  4025. is machine-dependent on both the target environment and the Ada compiler
  4026. used.  This data is not provided.
  4027. .SECT 1 3.2. CSCI design description.
  4028. .PP
  4029. This section discusses the following CSCs (Computer Software Components).
  4030. .li +5
  4031. .LIST 4
  4032. .LE Console
  4033. .LE Input_File
  4034. .LE Output_File
  4035. .LE Command_Symbols
  4036. .LE Error_Log
  4037. .LE Index
  4038. .LE Variable
  4039. .LE Parse
  4040. .LE Formatted_Output_File
  4041. .LE Contents
  4042. .LE Environment
  4043. .LE Macro
  4044. .LE Command
  4045. .LE Word_Processor
  4046. .ELIST
  4047. .li -5
  4048. .PP
  4049. The design descriptions which follow are brief summaries of the information
  4050. available in the associated package and subprogram specifications.
  4051. .SECT 2 3.2.1 Console
  4052. .SECT 3 3.2.1.1 Purpose
  4053. .PP
  4054. Console implements an abstract state machine of a console terminal.
  4055. Console offers an abstraction that can be made more efficient
  4056. by not using Text_IO (and having its associated overhead imposed)
  4057. if possible.
  4058. .SECT 3 3.2.1.2 Data Types, Constants, and Variables
  4059. .PP
  4060. None
  4061. .SECT 3 3.2.1.3 Methods
  4062. .li +5
  4063. .LIST 4
  4064. .LE Put (Character and String)
  4065. .LE Put_Line
  4066. .LE New_Line
  4067. .LE Get_Line
  4068. .ELIST
  4069. .li -5
  4070. .SECT 3 3.2.1.4 Exceptions Raised
  4071. .PP
  4072. None
  4073. .SECT 2 3.2.2 Input_File
  4074. .SECT 3 3.2.2.1 Purpose
  4075. .PP
  4076. Input_File implements an abstract data type of an input file.
  4077. Input_File offers an abstraction that can be made more efficient by
  4078. not using Text_IO (and having its associated overhead imposed)
  4079. if possible.
  4080. .SECT 3 3.2.2.2 Data Types, Constants, and Variables
  4081. .PP
  4082. File_Type
  4083. .SECT 3 3.2.2.3 Methods
  4084. .li +5
  4085. .LIST 4
  4086. .LE Open
  4087. .LE Get_Line
  4088. .LE End_Of_File
  4089. .LE Close
  4090. .ELIST
  4091. .li -5
  4092. .SECT 3 3.2.2.4 Exceptions Raised
  4093. .PP
  4094. Cannot_Open_Input_File
  4095. .PP
  4096. Read_Error
  4097. .SECT 2 3.2.3 Output_File
  4098. .SECT 3 3.2.3.1 Purpose
  4099. .PP
  4100. Output_File implements an abstract data type of an output file.
  4101. Output_File offers an abstraction that can be made more efficient
  4102. by not using Text_IO (and having its associated overhead imposed)
  4103. if possible and also offers the ability to suppress the output,
  4104. which may be desired if a caller is skipping over pages and
  4105. just wants to output to a null device during this process.
  4106. .SECT 3 3.2.3.2 Data Types, Constants, and Variables
  4107. .PP
  4108. File_Type
  4109. .SECT 3 3.2.3.3 Methods
  4110. .li +5
  4111. .LIST 4
  4112. .LE Already_Exists
  4113. .LE Delete
  4114. .LE Create
  4115. .LE Put
  4116. .LE Put_Line
  4117. .LE New_Line
  4118. .LE New_Page
  4119. .LE Enable_Output
  4120. .LE Disable_Output
  4121. .LE Close
  4122. .ELIST
  4123. .li -5
  4124. .SECT 3 3.2.3.4 Exceptions Raised
  4125. .PP
  4126. Cannot_Create_Output_File
  4127. .PP
  4128. Write_Error
  4129. .SECT 2 3.2.4 Command_Symbols
  4130. .SECT 3 3.2.4.1 Purpose
  4131. .PP
  4132. Command_Symbols contains the command name table used by the body of
  4133. package Command.  It also contains all the error messages issued by
  4134. routines which output to the Error_Log.
  4135. .SECT 3 3.2.4.2 Data Types, Constants, and Variables
  4136. .li +5
  4137. .LIST 4
  4138. .LE Command_Text_Length (Constant)
  4139. .PP
  4140. This is the maximum length of the text of a command verb.  If this value
  4141. is changed, the table entries in Cl must be changed as well.
  4142. .LE Ltw_Length (Constant)
  4143. .LE COMMAND_ID (Type)
  4144. .PP
  4145. This is an enumeration type which uniquely names each of the commands
  4146. recognized by the package Command.
  4147. .LE COMMAND_TEXT (Type)
  4148. .PP
  4149. COMMAND_TEXT is a string of length Command_Text_Length.
  4150. .LE COMMAND_DEFINITION (Type)
  4151. .PP
  4152. COMMAND_DEFINITION is a record containing a COMMAND_ID and a COMMAND_TEXT.
  4153. It is used to define each of the command verbs.
  4154. .LE COMMAND_LIST (Type)
  4155. .PP
  4156. COMMAND_LIST is a vector of COMMAND_DEFINITION objects.
  4157. .LE Cl (Variable)
  4158. .PP
  4159. Cl is of type COMMAND_LIST and contains all recognized commands.
  4160. It is a variable rather than a constant so that command names may be changed.
  4161. .LE Error_* (Constant)
  4162. .PP
  4163. These are the general-purpose and internal error messages.  They include
  4164. a paragraph number in the
  4165. .ul
  4166. PTF 1.2 Software User's Manual
  4167. which discusses the error.
  4168. .LE Warning_* (Constant)
  4169. .PP
  4170. These are the warning messages.  They include a paragraph number in the
  4171. .ul
  4172. PTF 1.2 Software User's Manual
  4173. which discusses the warning.
  4174. .ELIST
  4175. .li -5
  4176. .SECT 3 3.2.4.3 Methods
  4177. .PP
  4178. None
  4179. .SECT 3 3.2.4.4 Exceptions Raised
  4180. .PP
  4181. None
  4182. .SECT 2 3.2.5 Error_Log
  4183. .SECT 3 3.2.5.1 Purpose
  4184. .PP
  4185. Error_Log is used to log error message and warning messages to an output
  4186. file or standard output (the console).
  4187. .SECT 3 3.2.5.2 Data Types, Constants, and Variables
  4188. .PP
  4189. None
  4190. .SECT 3 3.2.5.3 Methods
  4191. .li +5
  4192. .LIST 4
  4193. .LE Open
  4194. .LE Write_Error
  4195. .LE Write_Warning
  4196. .LE Close
  4197. .ELIST
  4198. .li -5
  4199. .SECT 3 3.2.5.4 Exceptions Raised
  4200. .PP
  4201. None
  4202. .SECT 2 3.2.6 Index
  4203. .SECT 3 3.2.6.1 Purpose
  4204. .PP
  4205. Index is an abstract state machine which implements an index of a document.
  4206. .SECT 3 3.2.6.2 Data Types, Constants, and Variables
  4207. .PP
  4208. None
  4209. .SECT 3 3.2.6.3 Methods
  4210. .li +5
  4211. .LIST 4
  4212. .LE Create
  4213. .LE Add_Entry
  4214. .LE Close
  4215. .ELIST
  4216. .li -5
  4217. .SECT 3 3.2.6.4 Exceptions Raised
  4218. .PP
  4219. Index_File_Not_Open
  4220. .PP
  4221. Create_Error
  4222. .SECT 2 3.2.7 Variable
  4223. .SECT 3 3.2.7.1 Purpose
  4224. .PP
  4225. Variable defines and provides access to the following variables:
  4226. .li +5
  4227. .LIST 4
  4228. .LE Number registers a-z
  4229. .LE Command control character (CC)
  4230. .LE Escape character (EC)
  4231. .LE Flag character (FC)
  4232. .LE Auto-Paragraphing flag
  4233. .LE Bold line, center line, and underlined line counts
  4234. .LE Current file name and line number
  4235. .LE User-defined text variables
  4236. .ELIST
  4237. .li -5
  4238. .SECT 3 3.2.7.2 Data Types, Constants, and Variables
  4239. .li +5
  4240. .LIST 4
  4241. .LE Default_Auto_Paragraph (Constant)
  4242. .LE Default_Cc (Constant)
  4243. .LE Default_Ec (Constant)
  4244. .LE Default_Fc (Constant)
  4245. .LE NREG (Type)
  4246. .ELIST
  4247. .li -5
  4248. .SECT 3 3.2.7.3 Methods
  4249. .li +5
  4250. .LIST 4
  4251. .LE Set_Auto_Paragraph
  4252. .LE Is_Auto_Paragraph
  4253. .LE Set_Bold_Count
  4254. .LE Bold_Count
  4255. .LE Set_Center_Count
  4256. .LE Center_Count
  4257. .LE Set_Underline_Count
  4258. .LE Underline_Count
  4259. .LE Set_Cc
  4260. .LE Cc
  4261. .LE Set_Ec
  4262. .LE Ec
  4263. .LE Set_Fc
  4264. .LE Fc
  4265. .LE Set_Nr
  4266. .LE Nr (as a NATURAL and as a STRING)
  4267. .LE Set_Var
  4268. .LE Var (as a function and as a procedure)
  4269. .LE Set_File_Name
  4270. .LE Get_File_Name
  4271. .LE Set_Line_Number
  4272. .LE Increment_Line_Number
  4273. .LE Line_Number
  4274. .ELIST
  4275. .li -5
  4276. .SECT 3 3.2.7.4 Exceptions Raised
  4277. .PP
  4278. None
  4279. .SECT 2 3.2.8 Parse
  4280. .SECT 3 3.2.8.1 Purpose
  4281. .PP
  4282. Parse parses the input string, which does not begin with a dot, into
  4283. the strings Command_Verb and Command_Tail.  Verb_Last and Tail_Last are
  4284. set to the index of the last valid character.  Command_Verb starts with
  4285. the first character.  Command_Tail starts with the first non-blank character
  4286. after the verb.  The string Item is of the form:
  4287. .sp
  4288. .ce
  4289. command_verb  command_tail
  4290. .sp
  4291. .SECT 3 3.2.8.2 Data Types, Constants, and Variables
  4292. .PP
  4293. None
  4294. .SECT 3 3.2.8.3 Methods
  4295. .PP
  4296. None -- this is a procedure.
  4297. .SECT 3 3.2.8.4 Exceptions Raised
  4298. .PP
  4299. None
  4300. .SECT 2 3.2.9 Formatted_Output_File
  4301. .SECT 3 3.2.9.1 Purpose
  4302. .PP
  4303. Formatted_Output_File manipulates text, placing
  4304. text into the output file as it is received.  Formatted_Output_File is
  4305. also used to define the format of the formatted text (number of lines
  4306. per page, header lines, etc.).
  4307. .SECT 3 3.2.9.2 Data Types, Constants, and Variables
  4308. .PP
  4309. FILE is the abstract data type managed as a Formatted_Output_File.
  4310. .PP
  4311. Constants:
  4312. .li +5
  4313. .LIST 4
  4314. .LE Maximum_Number_Of_Lines_On_Page
  4315. .LE Maximum_Line_Length
  4316. .PP
  4317. Note: this is an input line length.
  4318. The internal line length of the target line is five times this value.
  4319. .LE Maximum_Number_Of_Header_Footer_Lines
  4320. .PP
  4321. This is the number of header lines allowed.
  4322. It is also the number of footer lines allowed.
  4323. .LE Maximum_Number_Of_Pages
  4324. .PP
  4325. This is the size of the document which may be produced.
  4326. .LE Page_Attribute_Defaults
  4327. .PP
  4328. These are default values for the top margin, bottom margin, left margin, etc.
  4329. .LE Line_Attribute_Defaults
  4330. .PP
  4331. These are default values for bolding, centering, etc.
  4332. .LE Page_Number_Id_Default
  4333. .PP
  4334. This is the character that will be recognized as the page number in the
  4335. header and footer lines and in the table of contents and the index.
  4336. .ELIST
  4337. .li -5
  4338. .PP
  4339. Type definitions:
  4340. .li +5
  4341. .LIST 4
  4342. .LE PAGE_ATTRIBUTE
  4343. .PP
  4344. This is an enumeration type naming each of the page attributes
  4345. (top margin, etc.).
  4346. .LE LINE_ATTRIBUTE
  4347. .PP
  4348. This is an enumeration type naming each of the line attributes
  4349. (bold, etc.).
  4350. .LE PAGE_ATTRIBUTE_LIST
  4351. .LE OFF_ON
  4352. .LE LINE_ATTRIBUTE_LIST
  4353. .LE LINE_NUMBER
  4354. .LE HEADER_FOOTER_LINE
  4355. .LE PAGE_NUMBER
  4356. .LE STATUS
  4357. .PP
  4358. STATUS is returned by the Open method.
  4359. .LE PAGE_SIDE
  4360. .PP
  4361. PAGE_SIDE is used by the margin and indent setting methods.
  4362. .LE PAGE_KIND
  4363. .PP
  4364. PAGE_KIND is used by the header and footer setting methods.
  4365. .LE NUMERIC_FORMAT
  4366. .PP
  4367. NUMERIC_FORMAT is used for page numbers.
  4368. .ELIST
  4369. .li -5
  4370. .SECT 3 3.2.9.3 Methods
  4371. .li +5
  4372. .LIST 4
  4373. .LE Open
  4374. .LE Close
  4375. .LE Put_Invisible_Word
  4376. .LE Put_Word
  4377. .LE Put_Line
  4378. .LE Break_Line
  4379. .LE Current_Line
  4380. .LE Skip
  4381. .LE Break_Page (2 versions)
  4382. .LE Current_Page (2 versions)
  4383. .LE Set_Page_Number_Format (2 versions)
  4384. .LE Set_Page_Attribute
  4385. .LE Set_Line_Attribute
  4386. .LE Get_Page_Attribute
  4387. .LE Get_Line_Attribute
  4388. .LE Test_Page
  4389. .LE Set_Footer_Line
  4390. .LE Set_Header_Line
  4391. .LE Set_Page_Number_Id
  4392. .LE Page_Number_Format
  4393. .ELIST
  4394. .li -5
  4395. .SECT 3 3.2.9.4 Exceptions Raised
  4396. .PP
  4397. Range_Error
  4398. .PP
  4399. File_Not_Open
  4400. .SECT 2 3.2.10 Contents
  4401. .SECT 3 3.2.10.1 Purpose
  4402. .PP
  4403. Contents adds lines to the table of contents and prints the table of contents.
  4404. Once the table of contents has been printed, no more lines may be added to it.
  4405. .SECT 3 3.2.10.2 Data Types, Constants, and Variables
  4406. .PP
  4407. TABLE_NUMBER sets the number of tables of contents supported by this package.
  4408. .SECT 3 3.2.10.3 Methods
  4409. .li +5
  4410. .LIST 4
  4411. .LE Select_Table
  4412. .LE Add_Line
  4413. .LE Print
  4414. .ELIST
  4415. .li -5
  4416. .SECT 3 3.2.10.4 Exceptions Raised
  4417. .PP
  4418. None
  4419. .SECT 2 3.2.11 Environment
  4420. .SECT 3 3.2.11.1 Purpose
  4421. .PP
  4422. Environment provides a mechanism for saving the current environment
  4423. and then later restoring it.  The environment consists of the
  4424. items named under the ".save" command in the
  4425. .ul
  4426. PTF 1.2 Software User's Manual.
  4427. .SECT 3 3.2.11.2 Data Types, Constants, and Variables
  4428. .PP
  4429. None
  4430. .SECT 3 3.2.11.3 Methods
  4431. .li +5
  4432. .LIST 4
  4433. .LE Pop
  4434. .LE Push
  4435. .ELIST
  4436. .li -5
  4437. .SECT 3 3.2.11.4 Exceptions Raised
  4438. .PP
  4439. None
  4440. .SECT 2 3.2.12 Macro
  4441. .SECT 3 3.2.12.1 Purpose
  4442. .PP
  4443. Macro is used to manipulate an abstract state machine which contains
  4444. a group of macro definitions.  It provides routines for building new
  4445. macro definitions and extracting the lines from a macro definition.
  4446. .SECT 3 3.2.12.2 Data Types, Constants, and Variables
  4447. .PP
  4448. MACRO_ID is the abstract data type used by many of the methods below
  4449. to reference a particular macro.
  4450. .PP
  4451. MACRO_STATUS
  4452. .SECT 3 3.2.12.3 Methods
  4453. .li +5
  4454. .LIST 4
  4455. .LE Create
  4456. .LE Write
  4457. .LE Open
  4458. .LE Is_Empty
  4459. .LE Read
  4460. .LE Close
  4461. .LE Locate
  4462. .LE Define_Parameters
  4463. .ELIST
  4464. .li -5
  4465. .SECT 3 3.2.12.4 Exceptions Raised
  4466. .PP
  4467. Macro_Not_In_Add_Mode
  4468. .PP
  4469. Macro_Not_Open
  4470. .SECT 2 3.2.13 Command
  4471. .SECT 3 3.2.13.1 Purpose
  4472. .PP
  4473. Command provides all the command identification and processing functions
  4474. for the Word_Processor.
  4475. .SECT 3 3.2.13.2 Data Types, Constants, and Variables
  4476. .PP
  4477. None
  4478. .SECT 3 3.2.13.3 Methods
  4479. .li +5
  4480. .LIST 4
  4481. .LE Identify
  4482. .LE Process
  4483. .LE Disable_Bolding
  4484. .ELIST
  4485. .li -5
  4486. .SECT 3 3.2.13.4 Exceptions Raised
  4487. .PP
  4488. None
  4489. .SECT 2 3.2.14 Word_Processor
  4490. .SECT 3 3.2.14.1 Purpose
  4491. .PP
  4492. Word_Processor is an abstract state machine which reads one or more input
  4493. text files, processing text and commands from them,
  4494. placing the output into a common output file.  The output file must be
  4495. opened before any of the input files are processed.
  4496. .SECT 3 3.2.14.2 Data Types, Constants, and Variables
  4497. .PP
  4498. OPERATION_STATUS
  4499. .SECT 3 3.2.14.3 Methods
  4500. .li +5
  4501. .LIST 4
  4502. .LE Open_Output_File
  4503. .LE Process_Source_File
  4504. .ELIST
  4505. .li -5
  4506. .SECT 3 3.2.14.4 Exceptions Raised
  4507. .PP
  4508. Output_File_Not_Open
  4509. .bp
  4510. .cl
  4511. .SECT 0 4. Detailed design.
  4512. .PP
  4513. The detailed design information called for by DoD-STD-2167A is omitted
  4514. from this document.  The reader is referred to the source code, starting
  4515. with the Ada package specifications.
  4516. .bp
  4517. .cl
  4518. .SECT 0 5. CSCI data.
  4519. .PP
  4520. The global data elements are controlled by the packages Command_Symbols
  4521. and Variable.
  4522. .bp
  4523. .cl
  4524. .SECT 0 6. CSCI data files.
  4525. .PP
  4526. The following kinds of data files are manipulated by Ptf and Ptfidx:
  4527. .li +5
  4528. .LIST 4
  4529. .LE Input PTF source files
  4530. .LE Output ASCII text files
  4531. .LE @IDXFILE
  4532. .LE @PTFIDXFILE
  4533. .ELIST
  4534. .li -5
  4535. .SECT 1 6.1. Data file to CSC/CSU cross reference.
  4536. .PP
  4537. The following figure shows the disk files used in the PTF System.
  4538. .sp
  4539. .nf
  4540. .na
  4541.   Input                       Output
  4542.   PTF source  ----> Ptf ----> ASCII text
  4543.   Files             | ^       Files
  4544.                     | |
  4545.         @IDXFILE     | | @PTFIDXFILE
  4546.                     V |
  4547.                    Ptfidx
  4548. .fi
  4549. .ap
  4550. .SECT 1 6.2. @IDXFILE Data File
  4551. .PP
  4552. The "@IDXFILE" data file is generated by Ptf if there are index entries
  4553. present in one or more Input PTF Source Files.  This file is read and
  4554. processed by Ptfidx.
  4555. .SECT 1 6.3 @PTFIDXFILE Data File
  4556. .PP
  4557. The "@PTFIDXFILE" data file is generated by Ptfidx after processing
  4558. the "@IDXFILE" data file.  "@PTFIDXFILE" can be processed by Ptf to
  4559. produce a dual-column index.
  4560. .bp
  4561. .cl
  4562. .SECT 0 7. Requirements traceability.
  4563. .PP
  4564. This section is omitted.  The requirements document was the
  4565. .ul
  4566. PROFF User's Guide Version 1.0.
  4567. .bp
  4568. .cl
  4569. .SECT 0 8. Notes.
  4570. .SECT 1 8.1 Acronyms
  4571. .ec
  4572. .include ptfacr.ptf
  4573. .ec \
  4574. .comment
  4575. .! The table of contents is automatically generated and placed
  4576. .! here in the document file.  It should be physically moved to
  4577. .! after the title page after printing the document.
  4578. .comment
  4579. .bp 2
  4580. .pn lower_roman #
  4581. .ce
  4582. .ul
  4583. Table of Contents
  4584. .sp 2
  4585. .pc
  4586. .comment
  4587. .! This is provided in case the table of contents ends on an odd
  4588. .! page number.
  4589. .comment
  4590. .bp
  4591. .sp 20
  4592. .ce
  4593. This page intentionally blank
  4594. --::::::::::
  4595. --ptfacr.ptf
  4596. --::::::::::
  4597. .sp
  4598. .nf
  4599. .nap
  4600. .li +5
  4601. .ul
  4602. Acronym    Meaning
  4603.  
  4604. ASR        Ada Software Repository
  4605. CDRL       Contract Data Requirements List
  4606. CSCI       Computer Software Configuration Item
  4607. DID        Data Item Descriptor
  4608. DoD-STD-2167A
  4609.            "Military Standard Defense System Software
  4610.            Development"
  4611. FOF        Formatted__Output__File
  4612. MIL-HDBK-1804
  4613.            "Ada Style Guide"
  4614. PDL        Program Design Language
  4615. PTF        Portable Text Formatter
  4616. PTFIDX     Portable Text Formatter Indexer
  4617. SIMTEL20   SIMulation and TELeprocessing DECSystem-20
  4618. WSMR       White Sands Missile Range
  4619. WSMR-SIMTEL20.ARMY.MIL
  4620.            name of host computer on which the
  4621.            Ada Software Repository resides
  4622. .li -5
  4623. .fi
  4624. .ap
  4625. --::::::::::
  4626. --ptfover.ptf
  4627. --::::::::::
  4628. .PP
  4629. The
  4630. .ul
  4631. Portable Text Formatter
  4632. (PTF)
  4633. is a document formatting program, written in Ada, which can execute
  4634. on a variety of hardware platforms.  PTF was designed to be as portable
  4635. as possible, so it should run on any platform supported by a validated
  4636. Ada compiler.
  4637. .PP
  4638. PTF reads one or more source text files which contain both commands to PTF
  4639. and text lines, and PTF
  4640. generates a formatted output file and (optionally)
  4641. a file containing index entries.
  4642. Commands to PTF are placed on lines whose first
  4643. character is a dot (this may be changed if desired), and
  4644. text lines are those lines whose first character is not a dot.
  4645. Commands to PTF instruct it to perform certain operations on the
  4646. formatted output file, such as set left margin, underline the
  4647. following words, place an entry into the table of contents, place an
  4648. entry into the index, and define a macro.
  4649. .PP
  4650. PTF was designed to meet several objectives:
  4651. .li +2
  4652. .LIST 4
  4653. .LE Generate DoD-STD-2167A documents.
  4654. .PP
  4655. PTF was designed specifically to support the generation of DoD-STD-2167A
  4656. documents, as detailed in the DoD-STD-2167A Data Item Descriptors (DIDs).
  4657. To this end, PTF supports multiple page heading lines, multiple page footer
  4658. lines, page numbers in a variety of formats (including Arabic and Roman
  4659. numeral), generation of
  4660. up to six distinct tables of contents (so that separate tables
  4661. for figures and diagrams may be created), and generation of an index.
  4662. .LE Support Ada software development.
  4663. .PP
  4664. PTF was written to provide a mechanism to support other Ada software
  4665. development tools, such as Ada PDL (Program Design Language) processors.
  4666. Output from these tools would be text files containing PTF commands.
  4667. Specifically, support of such tools to process PDL as defined in
  4668. MIL-HDBK-1804 is anticipated.
  4669. .LE Support team development of a document.
  4670. .PP
  4671. PTF also supports team development of a document, where individuals can
  4672. be given a common set of macros and instructions on their use, and PTF can
  4673. assemble a document in a common format from many different source files
  4674. which were independently created.
  4675. .LE Provide a documentation standard for the Ada Software Repository.
  4676. .PP
  4677. Many of the reusable documents in the
  4678. Ada Software Repository will be revised so they may be processed by PTF,
  4679. and many new documents will be released in a form that may be processed
  4680. by PTF.
  4681. .LE Port without modification to computers which have validated Ada compilers.
  4682. .PP
  4683. PTF is written in Ada and has been tested on a VAX, Sun, and PC platform
  4684. in an attempt to insure portability.
  4685. .ELIST
  4686. .li -2
  4687. .PP
  4688. PTFIDX is a companion program to PTF which processes its index pages.
  4689. .index PTFIDX
  4690. --::::::::::
  4691. --zzz2167a.ptf
  4692. --::::::::::
  4693. .comment
  4694. .! Useful Macros (note that macros are in upper-case):
  4695. .!   .SECT <indentation level> <number> <text>
  4696. .!       -- define a section which appears in the document and the
  4697. .!       -- table of contents
  4698. .!   .LIST <number of spaces to indent>
  4699. .!       -- start a list of items; the list will be indented from the
  4700. .!       -- right and left by the indicated number of spaces;
  4701. .!       -- nothing is output by this macro -- only the indentation
  4702. .!       -- is changed and the number of the next list element
  4703. .!       -- is set
  4704. .!   .LE <text>
  4705. .!       -- enter a new list item into the list; this may be
  4706. .!       -- followed by more lines containing text associated
  4707. .!       -- with the list entry; a blank line is generated followed
  4708. .!       -- by a list element number, a period, and <text> extended
  4709. .!       -- to the left by the <number of spaces to indent> set by
  4710. .!       -- the .LIST macro
  4711. .!   .ELIST
  4712. .!       -- end a list of items; the indentation set by .LIST is
  4713. .!       -- unset; a break is issued
  4714. .!   .SLIST <number of spaces to indent>
  4715. .!       -- start a sublist of items while in a list; the sublist will
  4716. .!       -- be further indented from the right and left by the
  4717. .!       -- indicated number of spaces
  4718. .!   .SLE <text>
  4719. .!       -- enter a new list item into the sublist; this may be
  4720. .!       -- followed by more lines containing text associated
  4721. .!       -- with the sublist entry; a blank line is generated
  4722. .!       -- followed by N.M (N=list element number, M=sublist number),
  4723. .!       -- a period, and <text> extended to the left by the
  4724. .!       -- <number of spaces to indent> set by the .SLIST macro
  4725. .!   .ESLIST
  4726. .!       -- end a sublist of items and continue with the list
  4727. .!   .PP
  4728. .!       -- skip a line and start a new paragraph, indented by 5
  4729. .!       -- spaces
  4730. .comment
  4731. .!
  4732. .! Macro: SECT
  4733. .!
  4734. .define SECT
  4735. .contline @1 @2 @3 @4 @5 @6 @7 @8 @9
  4736. .sp 2
  4737. .ne 10
  4738. @2
  4739. .ul
  4740. @3 @4 @5 @6 @7 @8 @9
  4741. .br
  4742. .en
  4743. .!
  4744. .! Macro: LIST
  4745. .!
  4746. .define LIST
  4747. .vs LISTINDENT @1
  4748. .li +@LISTINDENT
  4749. .ri +@LISTINDENT
  4750. .nr a 0
  4751. .en
  4752. .!
  4753. .! Macro: LE
  4754. .!
  4755. .define LE
  4756. .sp
  4757. .ti -@LISTINDENT
  4758. .nr a +1
  4759. @na.
  4760. @1 @2 @3 @4 @5 @6 @7 @8 @9
  4761. .br
  4762. .en
  4763. .!
  4764. .! Macro: ELIST
  4765. .!
  4766. .define ELIST
  4767. .br
  4768. .li -@LISTINDENT
  4769. .ri -@LISTINDENT
  4770. .en
  4771. .!
  4772. .! Macro: SLIST
  4773. .!
  4774. .define SLIST
  4775. .vs SLISTINDENT @1
  4776. .li +@SLISTINDENT
  4777. .ri +@SLISTINDENT
  4778. .nr b 0
  4779. .en
  4780. .!
  4781. .! Macro: SLE
  4782. .!
  4783. .define SLE
  4784. .sp
  4785. .ti -@SLISTINDENT
  4786. .nr b +1
  4787. @na.@nb.
  4788. @1 @2 @3 @4 @5 @6 @7 @8 @9
  4789. .br
  4790. .en
  4791. .!
  4792. .! Macro: ESLIST
  4793. .!
  4794. .define ESLIST
  4795. .br
  4796. .li -@SLISTINDENT
  4797. .ri -@SLISTINDENT
  4798. .en
  4799. .!
  4800. .! Macro: PP
  4801. .!
  4802. .define PP
  4803. .sp
  4804. .ti +5
  4805. .en
  4806. --::::::::::
  4807. --ptfpcr01.ptf
  4808. --::::::::::
  4809. .comment
  4810. .! Problem/Change Report as per DoD-STD-2167A
  4811. .!   This template is compliant with the requirements in the main
  4812. .! document of DoD-STD-2167A.  This template may be readily altered
  4813. .! and still be compliant with DoD-STD-2167A since the guidelines
  4814. .! presented in the documentation are very general.
  4815. .comment
  4816. .vs SYSNAME Portable Text Formatter
  4817. .vs DATE 2 Apr 90
  4818. .vs ID PTF-01
  4819. .lm 11
  4820. .rm 70
  4821. .nlheader 3
  4822. .he 1 ''Problem/Change Report''
  4823. .he 2 /@SYSNAME/@ID/@DATE/
  4824. .nlfooter 2
  4825. .fo 2 //Page #//
  4826. .de PP
  4827. .sp
  4828. .ti +5
  4829. .en
  4830. .de SECT
  4831. .sp 2
  4832. .tp 10
  4833. ------------------------------------------------------------
  4834. .nr s +1
  4835. Section @ns --
  4836. .ul
  4837. @1 @2 @3 @4 @5 @6 @7 @8 @9
  4838. .sp
  4839. .en
  4840. .nr s 0
  4841. .sp 2
  4842. .ce on
  4843. Problem/Change Report
  4844. .sp
  4845. for
  4846. .sp
  4847. @SYSNAME
  4848. .ce off
  4849. .sp 2
  4850. .SECT Software System Identification
  4851. .nf
  4852.   System Name: @SYSNAME
  4853.   Version Number: 1.0
  4854.   Version Date (if known): Unknown
  4855. .fi
  4856. .SECT Identification of Person Reporting Problem
  4857. .nf
  4858.   Name: Richard Conn
  4859.   Address:
  4860.     White Sands
  4861.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  4862.   Phone: N/A
  4863. .fi
  4864. .SECT Problem Classification and Description
  4865. .nf
  4866.   Classification of Problem by Category
  4867.   (Check all that apply):
  4868.     Software Problem
  4869.     Documentation Problem
  4870.   X Design Problem
  4871.   Classification of Problem by Priority
  4872.   (Check all that apply, see Appendix A for descriptions):
  4873.     Priority 1
  4874.     Priority 2
  4875.     Priority 3
  4876.   X Priority 4
  4877.     Priority 5
  4878. .fi
  4879. .sp 2
  4880. .tp 10
  4881. .ul
  4882. Description of Problem
  4883. .PP
  4884. When formatting PTF files to be displayed on a video screen
  4885. (for review prior to printing or for display to an audience),
  4886. the underlining of text obliterates the text, resulting in only
  4887. the underlining being displayed.
  4888. .PP
  4889. It is desirable to add a command-line option to disable underlining.
  4890. An option to disable bold facing already exists.
  4891. .SECT Corrective Action
  4892. .sp
  4893. .ul
  4894. Person to whom Corrective Action is assigned
  4895. .sp
  4896. .nf
  4897.     Richard Conn
  4898. .fi
  4899. .sp
  4900. .ul
  4901. Recommended Corrective Action Needed to Resolve Problem
  4902. .sp
  4903. .PP
  4904. Add command-line options as follows:
  4905. .sp
  4906. .nf
  4907.   -du     to disable underlining
  4908.   -da     to disable both underlining and bold facing
  4909. .fi
  4910. .PP
  4911. Also add .du and .eu commands which may be processed internally.
  4912. .sp 2
  4913. .ul
  4914. Actions Actually Taken to Resolve Problem
  4915. .PP
  4916. The command-line options -du and -da have been added.  The new
  4917. verbs .du and .eu have been added.
  4918. .PP
  4919. The following files associated with the PTF system were affected:
  4920. .sp
  4921. .nf
  4922.   ptf.a                   -- mainline
  4923.   wp.a and wp__body.a      -- for -du and -da option processing
  4924.   cmd.a and cmd__body.a    -- for .du and .eu command processing
  4925.   env.a and env__body.a    -- for environment push/pop
  4926.   cmd__sym.a               -- for .du and .eu command symbols
  4927. .fi
  4928. .bp
  4929. .sp 20
  4930. .ce
  4931. This Page Intentionally Blank
  4932. .bp 1
  4933. .pn arabic A-#
  4934. .ce
  4935. .ul
  4936. Appendix A: Priority Descriptions by Number
  4937. .sp 2
  4938. 1: A software problem that does one of the following:
  4939. .br
  4940. .li +5
  4941. .ri +5
  4942. .sp
  4943. Prevents the accomplishment of an operational
  4944. or mission essential capability specified by
  4945. baselined requirements,
  4946. .sp
  4947. Prevents the operator's
  4948. accomplishment of an operational or mission
  4949. essential capability, or
  4950. .sp
  4951. Jeoparidzes personnel
  4952. safety.
  4953. .li -5
  4954. .ri -5
  4955. .sp
  4956. 2: A software problem that does one of the following:
  4957. .br
  4958. .li +5
  4959. .ri +5
  4960. .sp
  4961. Adversely affects the operator's accomplishment
  4962. of an operational or mission essential
  4963. capability specified by baselined requirements
  4964. so as to degrade performance and for which no
  4965. alternative work-around solution is known or
  4966. .sp
  4967. Adversely affects the operator's accomplishment
  4968. of an operational or mission essential capability
  4969. specified by baselined requirements so as to
  4970. degrade performance and for which no alternative
  4971. work-around solution is known.
  4972. .li -5
  4973. .ri -5
  4974. .sp
  4975. 3: A software problem that does one of the following:
  4976. .br
  4977. .li +5
  4978. .ri +5
  4979. .sp
  4980. Adversely affects the accomplishment of an
  4981. operational or mission essential capability
  4982. specified by baselined requirements so as to
  4983. degrade performance and for which an alternative
  4984. work-around solution is known or
  4985. .sp
  4986. Adversely
  4987. affects the operator's accomplishment of an
  4988. operational or mission essential capability
  4989. specified by baselined requirements so as to
  4990. degrade performance and for which an alternative
  4991. work-around solution is known.
  4992. .li -5
  4993. .ri -5
  4994. .sp
  4995. 4: A software problem that is an operator inconvenience
  4996. or annoyance and which does not affect a required
  4997. operational or mission essential capability
  4998. .sp
  4999. 5: All other errors
  5000. .bp
  5001. .sp 20
  5002. .ce
  5003. This Page Intentionally Blank
  5004. --::::::::::
  5005. --ptfpcr02.ptf
  5006. --::::::::::
  5007. .comment
  5008. .! Problem/Change Report as per DoD-STD-2167A
  5009. .!   This template is compliant with the requirements in the main
  5010. .! document of DoD-STD-2167A.  This template may be readily altered
  5011. .! and still be compliant with DoD-STD-2167A since the guidelines
  5012. .! presented in the documentation are very general.
  5013. .comment
  5014. .vs SYSNAME Portable Text Formatter
  5015. .vs DATE 2 Apr 90
  5016. .vs ID PTF-02
  5017. .lm 11
  5018. .rm 70
  5019. .nlheader 3
  5020. .he 1 ''Problem/Change Report''
  5021. .he 2 /@SYSNAME/@ID/@DATE/
  5022. .nlfooter 2
  5023. .fo 2 //Page #//
  5024. .de PP
  5025. .sp
  5026. .ti +5
  5027. .en
  5028. .de SECT
  5029. .sp 2
  5030. .tp 10
  5031. ------------------------------------------------------------
  5032. .nr s +1
  5033. Section @ns --
  5034. .ul
  5035. @1 @2 @3 @4 @5 @6 @7 @8 @9
  5036. .sp
  5037. .en
  5038. .nr s 0
  5039. .sp 2
  5040. .ce on
  5041. Problem/Change Report
  5042. .sp
  5043. for
  5044. .sp
  5045. @SYSNAME
  5046. .ce off
  5047. .sp 2
  5048. .SECT Software System Identification
  5049. .nf
  5050.   System Name: @SYSNAME
  5051.   Version Number: 1.0
  5052.   Version Date (if known): Unknown
  5053. .fi
  5054. .SECT Identification of Person Reporting Problem
  5055. .nf
  5056.   Name: Richard Conn
  5057.   Address:
  5058.     White Sands
  5059.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  5060.   Phone: N/A
  5061. .fi
  5062. .SECT Problem Classification and Description
  5063. .nf
  5064.   Classification of Problem by Category
  5065.   (Check all that apply):
  5066.   X Software Problem
  5067.     Documentation Problem
  5068.     Design Problem
  5069.   Classification of Problem by Priority
  5070.   (Check all that apply, see Appendix A for descriptions):
  5071.     Priority 1
  5072.     Priority 2
  5073.     Priority 3
  5074.   X Priority 4
  5075.     Priority 5
  5076. .fi
  5077. .sp 2
  5078. .tp 10
  5079. .ul
  5080. Description of Problem
  5081. .PP
  5082. If only one argument is given to PTF by accident (that is, an
  5083. input file is specified but an output file is not), PTF processes
  5084. as though all was all right with no indication of a problem.
  5085. .SECT Corrective Action
  5086. .sp
  5087. .ul
  5088. Person to whom Corrective Action is assigned
  5089. .sp
  5090. .nf
  5091.     Richard Conn
  5092. .fi
  5093. .sp
  5094. .ul
  5095. Recommended Corrective Action Needed to Resolve Problem
  5096. .sp
  5097. .PP
  5098. Check for a single argument and issue an error message.
  5099. .sp 2
  5100. .ul
  5101. Actions Actually Taken to Resolve Problem
  5102. .PP
  5103. The error in the argument checking mechanism has been identified and
  5104. repaired.
  5105. .PP
  5106. The following files associated with the PTF system were affected:
  5107. .sp
  5108. .nf
  5109.   ptf.a                   -- mainline
  5110. .fi
  5111. .bp
  5112. .sp 20
  5113. .ce
  5114. This Page Intentionally Blank
  5115. .bp 1
  5116. .pn arabic A-#
  5117. .ce
  5118. .ul
  5119. Appendix A: Priority Descriptions by Number
  5120. .sp 2
  5121. 1: A software problem that does one of the following:
  5122. .br
  5123. .li +5
  5124. .ri +5
  5125. .sp
  5126. Prevents the accomplishment of an operational
  5127. or mission essential capability specified by
  5128. baselined requirements,
  5129. .sp
  5130. Prevents the operator's
  5131. accomplishment of an operational or mission
  5132. essential capability, or
  5133. .sp
  5134. Jeoparidzes personnel
  5135. safety.
  5136. .li -5
  5137. .ri -5
  5138. .sp
  5139. 2: A software problem that does one of the following:
  5140. .br
  5141. .li +5
  5142. .ri +5
  5143. .sp
  5144. Adversely affects the operator's accomplishment
  5145. of an operational or mission essential
  5146. capability specified by baselined requirements
  5147. so as to degrade performance and for which no
  5148. alternative work-around solution is known or
  5149. .sp
  5150. Adversely affects the operator's accomplishment
  5151. of an operational or mission essential capability
  5152. specified by baselined requirements so as to
  5153. degrade performance and for which no alternative
  5154. work-around solution is known.
  5155. .li -5
  5156. .ri -5
  5157. .sp
  5158. 3: A software problem that does one of the following:
  5159. .br
  5160. .li +5
  5161. .ri +5
  5162. .sp
  5163. Adversely affects the accomplishment of an
  5164. operational or mission essential capability
  5165. specified by baselined requirements so as to
  5166. degrade performance and for which an alternative
  5167. work-around solution is known or
  5168. .sp
  5169. Adversely
  5170. affects the operator's accomplishment of an
  5171. operational or mission essential capability
  5172. specified by baselined requirements so as to
  5173. degrade performance and for which an alternative
  5174. work-around solution is known.
  5175. .li -5
  5176. .ri -5
  5177. .sp
  5178. 4: A software problem that is an operator inconvenience
  5179. or annoyance and which does not affect a required
  5180. operational or mission essential capability
  5181. .sp
  5182. 5: All other errors
  5183. .bp
  5184. .sp 20
  5185. .ce
  5186. This Page Intentionally Blank
  5187. --::::::::::
  5188. --ptfpcr03.ptf
  5189. --::::::::::
  5190. .comment
  5191. .! Problem/Change Report as per DoD-STD-2167A
  5192. .!   This template is compliant with the requirements in the main
  5193. .! document of DoD-STD-2167A.  This template may be readily altered
  5194. .! and still be compliant with DoD-STD-2167A since the guidelines
  5195. .! presented in the documentation are very general.
  5196. .comment
  5197. .vs SYSNAME Portable Text Formatter
  5198. .vs DATE 2 Apr 90
  5199. .vs ID PTF-03
  5200. .lm 11
  5201. .rm 70
  5202. .nlheader 3
  5203. .he 1 ''Problem/Change Report''
  5204. .he 2 /@SYSNAME/@ID/@DATE/
  5205. .nlfooter 2
  5206. .fo 2 //Page #//
  5207. .de PP
  5208. .sp
  5209. .ti +5
  5210. .en
  5211. .de SECT
  5212. .sp 2
  5213. .tp 10
  5214. ------------------------------------------------------------
  5215. .nr s +1
  5216. Section @ns --
  5217. .ul
  5218. @1 @2 @3 @4 @5 @6 @7 @8 @9
  5219. .sp
  5220. .en
  5221. .nr s 0
  5222. .sp 2
  5223. .ce on
  5224. Problem/Change Report
  5225. .sp
  5226. for
  5227. .sp
  5228. @SYSNAME
  5229. .ce off
  5230. .sp 2
  5231. .SECT Software System Identification
  5232. .nf
  5233.   System Name: @SYSNAME
  5234.   Version Number: 1.0
  5235.   Version Date (if known): Unknown
  5236. .fi
  5237. .SECT Identification of Person Reporting Problem
  5238. .nf
  5239.   Name: Richard Conn
  5240.   Address:
  5241.     White Sands
  5242.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  5243.   Phone: N/A
  5244. .fi
  5245. .SECT Problem Classification and Description
  5246. .nf
  5247.   Classification of Problem by Category
  5248.   (Check all that apply):
  5249.   X Software Problem
  5250.     Documentation Problem
  5251.     Design Problem
  5252.   Classification of Problem by Priority
  5253.   (Check all that apply, see Appendix A for descriptions):
  5254.     Priority 1
  5255.     Priority 2
  5256.     Priority 3
  5257.   X Priority 4
  5258.     Priority 5
  5259. .fi
  5260. .sp 2
  5261. .tp 10
  5262. .ul
  5263. Description of Problem
  5264. .PP
  5265. If an output file already exists, PTF recognizes this as described
  5266. and prompts the user to determine if he wishes to delete the file
  5267. and continue.  However, if the user says NO, the existing output file
  5268. is made empty (zero length).
  5269. .SECT Corrective Action
  5270. .sp
  5271. .ul
  5272. Person to whom Corrective Action is assigned
  5273. .sp
  5274. .nf
  5275.     Richard Conn
  5276. .fi
  5277. .sp
  5278. .ul
  5279. Recommended Corrective Action Needed to Resolve Problem
  5280. .sp
  5281. .PP
  5282. Modify code as required to not affect the output file if a
  5283. replacement of it is not desired.
  5284. .sp 2
  5285. .ul
  5286. Actions Actually Taken to Resolve Problem
  5287. .PP
  5288. The error has been identified and corrected.
  5289. .PP
  5290. The following files associated with the PTF system were affected:
  5291. .sp
  5292. .nf
  5293.   ptf.a                   -- mainline
  5294. .fi
  5295. .bp
  5296. .sp 20
  5297. .ce
  5298. This Page Intentionally Blank
  5299. .bp 1
  5300. .pn arabic A-#
  5301. .ce
  5302. .ul
  5303. Appendix A: Priority Descriptions by Number
  5304. .sp 2
  5305. 1: A software problem that does one of the following:
  5306. .br
  5307. .li +5
  5308. .ri +5
  5309. .sp
  5310. Prevents the accomplishment of an operational
  5311. or mission essential capability specified by
  5312. baselined requirements,
  5313. .sp
  5314. Prevents the operator's
  5315. accomplishment of an operational or mission
  5316. essential capability, or
  5317. .sp
  5318. Jeoparidzes personnel
  5319. safety.
  5320. .li -5
  5321. .ri -5
  5322. .sp
  5323. 2: A software problem that does one of the following:
  5324. .br
  5325. .li +5
  5326. .ri +5
  5327. .sp
  5328. Adversely affects the operator's accomplishment
  5329. of an operational or mission essential
  5330. capability specified by baselined requirements
  5331. so as to degrade performance and for which no
  5332. alternative work-around solution is known or
  5333. .sp
  5334. Adversely affects the operator's accomplishment
  5335. of an operational or mission essential capability
  5336. specified by baselined requirements so as to
  5337. degrade performance and for which no alternative
  5338. work-around solution is known.
  5339. .li -5
  5340. .ri -5
  5341. .sp
  5342. 3: A software problem that does one of the following:
  5343. .br
  5344. .li +5
  5345. .ri +5
  5346. .sp
  5347. Adversely affects the accomplishment of an
  5348. operational or mission essential capability
  5349. specified by baselined requirements so as to
  5350. degrade performance and for which an alternative
  5351. work-around solution is known or
  5352. .sp
  5353. Adversely
  5354. affects the operator's accomplishment of an
  5355. operational or mission essential capability
  5356. specified by baselined requirements so as to
  5357. degrade performance and for which an alternative
  5358. work-around solution is known.
  5359. .li -5
  5360. .ri -5
  5361. .sp
  5362. 4: A software problem that is an operator inconvenience
  5363. or annoyance and which does not affect a required
  5364. operational or mission essential capability
  5365. .sp
  5366. 5: All other errors
  5367. .bp
  5368. .sp 20
  5369. .ce
  5370. This Page Intentionally Blank
  5371. --::::::::::
  5372. --ptfpcr04.ptf
  5373. --::::::::::
  5374. .comment
  5375. .! Problem/Change Report as per DoD-STD-2167A
  5376. .!   This template is compliant with the requirements in the main
  5377. .! document of DoD-STD-2167A.  This template may be readily altered
  5378. .! and still be compliant with DoD-STD-2167A since the guidelines
  5379. .! presented in the documentation are very general.
  5380. .comment
  5381. .vs SYSNAME Portable Text Formatter
  5382. .vs DATE 2 Apr 90
  5383. .vs ID PTF-04
  5384. .lm 11
  5385. .rm 70
  5386. .nlheader 3
  5387. .he 1 ''Problem/Change Report''
  5388. .he 2 /@SYSNAME/@ID/@DATE/
  5389. .nlfooter 2
  5390. .fo 2 //Page #//
  5391. .de PP
  5392. .sp
  5393. .ti +5
  5394. .en
  5395. .de SECT
  5396. .sp 2
  5397. .tp 10
  5398. ------------------------------------------------------------
  5399. .nr s +1
  5400. Section @ns --
  5401. .ul
  5402. @1 @2 @3 @4 @5 @6 @7 @8 @9
  5403. .sp
  5404. .en
  5405. .nr s 0
  5406. .sp 2
  5407. .ce on
  5408. Problem/Change Report
  5409. .sp
  5410. for
  5411. .sp
  5412. @SYSNAME
  5413. .ce off
  5414. .sp 2
  5415. .SECT Software System Identification
  5416. .nf
  5417.   System Name: @SYSNAME
  5418.   Version Number: 1.0
  5419.   Version Date (if known): Unknown
  5420. .fi
  5421. .SECT Identification of Person Reporting Problem
  5422. .nf
  5423.   Name: Richard Conn
  5424.   Address:
  5425.     White Sands
  5426.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  5427.   Phone: N/A
  5428. .fi
  5429. .SECT Problem Classification and Description
  5430. .nf
  5431.   Classification of Problem by Category
  5432.   (Check all that apply):
  5433.   X Software Problem
  5434.     Documentation Problem
  5435.   X Design Problem
  5436.   Classification of Problem by Priority
  5437.   (Check all that apply, see Appendix A for descriptions):
  5438.     Priority 1
  5439.     Priority 2
  5440.     Priority 3
  5441.   X Priority 4
  5442.     Priority 5
  5443. .fi
  5444. .sp 2
  5445. .tp 10
  5446. .ul
  5447. Description of Problem
  5448. .PP
  5449. Variables identified by _@variablename have trailing spaces
  5450. appended to them.  This is not desirable in general.
  5451. .SECT Corrective Action
  5452. .sp
  5453. .ul
  5454. Person to whom Corrective Action is assigned
  5455. .sp
  5456. .nf
  5457.     Richard Conn
  5458. .fi
  5459. .sp
  5460. .ul
  5461. Recommended Corrective Action Needed to Resolve Problem
  5462. .sp
  5463. .PP
  5464. Do not add any extra trailing spaces after a parameter is resolved.
  5465. .sp 2
  5466. .ul
  5467. Actions Actually Taken to Resolve Problem
  5468. .PP
  5469. The error has been identified and corrected.
  5470. .PP
  5471. The following files associated with the PTF system were affected:
  5472. .sp
  5473. .nf
  5474.   cmd__body.a     COMMAND.PROCESS.PARSE__HF.SUB__PARSE
  5475.   fof__body.a     FOF.PUT__HEADER__FOOTER__LINE.BUILD__TEMP__STRING
  5476.   mac__body.a     MACRO.DEFINE__PARAMETERS
  5477.   wp_body.a       WP.EXPAND.EXPAND__VARIABLE
  5478. .fi
  5479. .bp
  5480. .sp 20
  5481. .ce
  5482. This Page Intentionally Blank
  5483. .bp 1
  5484. .pn arabic A-#
  5485. .ce
  5486. .ul
  5487. Appendix A: Priority Descriptions by Number
  5488. .sp 2
  5489. 1: A software problem that does one of the following:
  5490. .br
  5491. .li +5
  5492. .ri +5
  5493. .sp
  5494. Prevents the accomplishment of an operational
  5495. or mission essential capability specified by
  5496. baselined requirements,
  5497. .sp
  5498. Prevents the operator's
  5499. accomplishment of an operational or mission
  5500. essential capability, or
  5501. .sp
  5502. Jeoparidzes personnel
  5503. safety.
  5504. .li -5
  5505. .ri -5
  5506. .sp
  5507. 2: A software problem that does one of the following:
  5508. .br
  5509. .li +5
  5510. .ri +5
  5511. .sp
  5512. Adversely affects the operator's accomplishment
  5513. of an operational or mission essential
  5514. capability specified by baselined requirements
  5515. so as to degrade performance and for which no
  5516. alternative work-around solution is known or
  5517. .sp
  5518. Adversely affects the operator's accomplishment
  5519. of an operational or mission essential capability
  5520. specified by baselined requirements so as to
  5521. degrade performance and for which no alternative
  5522. work-around solution is known.
  5523. .li -5
  5524. .ri -5
  5525. .sp
  5526. 3: A software problem that does one of the following:
  5527. .br
  5528. .li +5
  5529. .ri +5
  5530. .sp
  5531. Adversely affects the accomplishment of an
  5532. operational or mission essential capability
  5533. specified by baselined requirements so as to
  5534. degrade performance and for which an alternative
  5535. work-around solution is known or
  5536. .sp
  5537. Adversely
  5538. affects the operator's accomplishment of an
  5539. operational or mission essential capability
  5540. specified by baselined requirements so as to
  5541. degrade performance and for which an alternative
  5542. work-around solution is known.
  5543. .li -5
  5544. .ri -5
  5545. .sp
  5546. 4: A software problem that is an operator inconvenience
  5547. or annoyance and which does not affect a required
  5548. operational or mission essential capability
  5549. .sp
  5550. 5: All other errors
  5551. .bp
  5552. .sp 20
  5553. .ce
  5554. This Page Intentionally Blank
  5555. --::::::::::
  5556. --ptfpcr05.ptf
  5557. --::::::::::
  5558. .comment
  5559. .! Problem/Change Report as per DoD-STD-2167A
  5560. .!   This template is compliant with the requirements in the main
  5561. .! document of DoD-STD-2167A.  This template may be readily altered
  5562. .! and still be compliant with DoD-STD-2167A since the guidelines
  5563. .! presented in the documentation are very general.
  5564. .comment
  5565. .vs SYSNAME Portable Text Formatter
  5566. .vs DATE 1 May 90
  5567. .vs ID PTF-05
  5568. .lm 11
  5569. .rm 70
  5570. .nlheader 3
  5571. .he 1 ''Problem/Change Report''
  5572. .he 2 /@SYSNAME/@ID/@DATE/
  5573. .nlfooter 2
  5574. .fo 2 //Page #//
  5575. .de PP
  5576. .sp
  5577. .ti +5
  5578. .en
  5579. .de SECT
  5580. .sp 2
  5581. .tp 10
  5582. ------------------------------------------------------------
  5583. .nr s +1
  5584. Section @ns --
  5585. .ul
  5586. @1 @2 @3 @4 @5 @6 @7 @8 @9
  5587. .sp
  5588. .en
  5589. .nr s 0
  5590. .sp 2
  5591. .ce on
  5592. Problem/Change Report
  5593. .sp
  5594. for
  5595. .sp
  5596. @SYSNAME
  5597. .ce off
  5598. .sp 2
  5599. .SECT Software System Identification
  5600. .nf
  5601.   System Name: @SYSNAME
  5602.   Version Number: 1.1
  5603.   Version Date (if known): Unknown
  5604. .fi
  5605. .SECT Identification of Person Reporting Problem
  5606. .nf
  5607.   Name: Richard Conn
  5608.   Address:
  5609.     White Sands
  5610.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  5611.   Phone: N/A
  5612. .fi
  5613. .SECT Problem Classification and Description
  5614. .nf
  5615.   Classification of Problem by Category
  5616.   (Check all that apply):
  5617.   X Software Problem
  5618.     Documentation Problem
  5619.     Design Problem
  5620.   Classification of Problem by Priority
  5621.   (Check all that apply, see Appendix A for descriptions):
  5622.   X Priority 1 (PTF cannot be compiled by Meridian Ada)
  5623.     Priority 2
  5624.     Priority 3
  5625.     Priority 4
  5626.     Priority 5
  5627. .fi
  5628. .sp 2
  5629. .tp 10
  5630. .ul
  5631. Description of Problem
  5632. .PP
  5633. PTF cannot be compiled with the Meridian AdaVantage 4.0 compiler
  5634. due to a bug in the way the compiler handles a package declaration
  5635. inside the body of a generic package.  The problem is with package
  5636. FILE__LISTER2 specifically.
  5637. .SECT Corrective Action
  5638. .sp
  5639. .ul
  5640. Person to whom Corrective Action is assigned
  5641. .sp
  5642. .nf
  5643.     Richard Conn
  5644. .fi
  5645. .sp
  5646. .ul
  5647. Recommended Corrective Action Needed to Resolve Problem
  5648. .sp
  5649. .PP
  5650. Modify FILE__LISTER2.A so that it can be compiled with Meridian AdaVantage 4.0
  5651. while still being able to be compiled with Verdix Ada and DEC Ada.
  5652. .sp 2
  5653. .ul
  5654. Actions Actually Taken to Resolve Problem
  5655. .PP
  5656. FILE__LISTER2.A was modified to allow compilation with Meridian AdaVantage 4.0.
  5657. .PP
  5658. The following files associated with the PTF system were affected:
  5659. .sp
  5660. .nf
  5661.   file__lister2.a
  5662. .fi
  5663. .bp
  5664. .sp 20
  5665. .ce
  5666. This Page Intentionally Blank
  5667. .bp 1
  5668. .pn arabic A-#
  5669. .ce
  5670. .ul
  5671. Appendix A: Priority Descriptions by Number
  5672. .sp 2
  5673. 1: A software problem that does one of the following:
  5674. .br
  5675. .li +5
  5676. .ri +5
  5677. .sp
  5678. Prevents the accomplishment of an operational
  5679. or mission essential capability specified by
  5680. baselined requirements,
  5681. .sp
  5682. Prevents the operator's
  5683. accomplishment of an operational or mission
  5684. essential capability, or
  5685. .sp
  5686. Jeoparidzes personnel
  5687. safety.
  5688. .li -5
  5689. .ri -5
  5690. .sp
  5691. 2: A software problem that does one of the following:
  5692. .br
  5693. .li +5
  5694. .ri +5
  5695. .sp
  5696. Adversely affects the operator's accomplishment
  5697. of an operational or mission essential
  5698. capability specified by baselined requirements
  5699. so as to degrade performance and for which no
  5700. alternative work-around solution is known or
  5701. .sp
  5702. Adversely affects the operator's accomplishment
  5703. of an operational or mission essential capability
  5704. specified by baselined requirements so as to
  5705. degrade performance and for which no alternative
  5706. work-around solution is known.
  5707. .li -5
  5708. .ri -5
  5709. .sp
  5710. 3: A software problem that does one of the following:
  5711. .br
  5712. .li +5
  5713. .ri +5
  5714. .sp
  5715. Adversely affects the accomplishment of an
  5716. operational or mission essential capability
  5717. specified by baselined requirements so as to
  5718. degrade performance and for which an alternative
  5719. work-around solution is known or
  5720. .sp
  5721. Adversely
  5722. affects the operator's accomplishment of an
  5723. operational or mission essential capability
  5724. specified by baselined requirements so as to
  5725. degrade performance and for which an alternative
  5726. work-around solution is known.
  5727. .li -5
  5728. .ri -5
  5729. .sp
  5730. 4: A software problem that is an operator inconvenience
  5731. or annoyance and which does not affect a required
  5732. operational or mission essential capability
  5733. .sp
  5734. 5: All other errors
  5735. .bp
  5736. .sp 20
  5737. .ce
  5738. This Page Intentionally Blank
  5739. --::::::::::
  5740. --ptfpcr06.ptf
  5741. --::::::::::
  5742. .comment
  5743. .! Problem/Change Report as per DoD-STD-2167A
  5744. .!   This template is compliant with the requirements in the main
  5745. .! document of DoD-STD-2167A.  This template may be readily altered
  5746. .! and still be compliant with DoD-STD-2167A since the guidelines
  5747. .! presented in the documentation are very general.
  5748. .comment
  5749. .vs SYSNAME Portable Text Formatter
  5750. .vs DATE 7 May 90
  5751. .vs ID PTF-06
  5752. .lm 11
  5753. .rm 70
  5754. .nlheader 3
  5755. .he 1 ''Problem/Change Report''
  5756. .he 2 /@SYSNAME/@ID/@DATE/
  5757. .nlfooter 2
  5758. .fo 2 //Page #//
  5759. .de PP
  5760. .sp
  5761. .ti +5
  5762. .en
  5763. .de SECT
  5764. .sp 2
  5765. .tp 10
  5766. ------------------------------------------------------------
  5767. .nr s +1
  5768. Section @ns --
  5769. .ul
  5770. @1 @2 @3 @4 @5 @6 @7 @8 @9
  5771. .sp
  5772. .en
  5773. .nr s 0
  5774. .sp 2
  5775. .ce on
  5776. Problem/Change Report
  5777. .sp
  5778. for
  5779. .sp
  5780. @SYSNAME
  5781. .ce off
  5782. .sp 2
  5783. .SECT Software System Identification
  5784. .nf
  5785.   System Name: @SYSNAME
  5786.   Version Number: 1.1
  5787.   Version Date (if known): Unknown
  5788. .fi
  5789. .SECT Identification of Person Reporting Problem
  5790. .nf
  5791.   Name: Richard Conn
  5792.   Address:
  5793.     White Sands
  5794.   Electronic Mail: rconn_@wsmr-simtel20.army.mil
  5795.   Phone: N/A
  5796. .fi
  5797. .SECT Problem Classification and Description
  5798. .nf
  5799.   Classification of Problem by Category
  5800.   (Check all that apply):
  5801.     Software Problem
  5802.     Documentation Problem
  5803.   X Design Problem
  5804.   Classification of Problem by Priority
  5805.   (Check all that apply, see Appendix A for descriptions):
  5806.     Priority 1
  5807.     Priority 2
  5808.     Priority 3
  5809.   X Priority 4
  5810.     Priority 5
  5811. .fi
  5812. .sp 2
  5813. .tp 10
  5814. .ul
  5815. Description of Problem
  5816. .PP
  5817. Include files cannot have lines which are PTF options (i.e.,
  5818. beginning with a single dash).  Lines in include files beginning
  5819. with either one or two dashes are interpreted as comments.
  5820. .PP
  5821. It is desirable to employ the new CLP package for this form
  5822. of command argument interface, as opposed to using CLI with
  5823. FILE__LISTER2.
  5824. .SECT Corrective Action
  5825. .sp
  5826. .ul
  5827. Person to whom Corrective Action is assigned
  5828. .sp
  5829. .nf
  5830.     Richard Conn
  5831. .fi
  5832. .sp
  5833. .ul
  5834. Recommended Corrective Action Needed to Resolve Problem
  5835. .sp
  5836. .PP
  5837. Use package CLP to implement the interface to the file names and options
  5838. given on the command line.
  5839. .sp 2
  5840. .ul
  5841. Actions Actually Taken to Resolve Problem
  5842. .PP
  5843. The use of FILE__LISTER2 was dropped.  CLP was used instead.
  5844. .PP
  5845. The following files associated with the PTF system were affected:
  5846. .sp
  5847. .nf
  5848.   ptf.a                   -- mainline
  5849. .fi
  5850. .bp
  5851. .sp 20
  5852. .ce
  5853. This Page Intentionally Blank
  5854. .bp 1
  5855. .pn arabic A-#
  5856. .ce
  5857. .ul
  5858. Appendix A: Priority Descriptions by Number
  5859. .sp 2
  5860. 1: A software problem that does one of the following:
  5861. .br
  5862. .li +5
  5863. .ri +5
  5864. .sp
  5865. Prevents the accomplishment of an operational
  5866. or mission essential capability specified by
  5867. baselined requirements,
  5868. .sp
  5869. Prevents the operator's
  5870. accomplishment of an operational or mission
  5871. essential capability, or
  5872. .sp
  5873. Jeoparidzes personnel
  5874. safety.
  5875. .li -5
  5876. .ri -5
  5877. .sp
  5878. 2: A software problem that does one of the following:
  5879. .br
  5880. .li +5
  5881. .ri +5
  5882. .sp
  5883. Adversely affects the operator's accomplishment
  5884. of an operational or mission essential
  5885. capability specified by baselined requirements
  5886. so as to degrade performance and for which no
  5887. alternative work-around solution is known or
  5888. .sp
  5889. Adversely affects the operator's accomplishment
  5890. of an operational or mission essential capability
  5891. specified by baselined requirements so as to
  5892. degrade performance and for which no alternative
  5893. work-around solution is known.
  5894. .li -5
  5895. .ri -5
  5896. .sp
  5897. 3: A software problem that does one of the following:
  5898. .br
  5899. .li +5
  5900. .ri +5
  5901. .sp
  5902. Adversely affects the accomplishment of an
  5903. operational or mission essential capability
  5904. specified by baselined requirements so as to
  5905. degrade performance and for which an alternative
  5906. work-around solution is known or
  5907. .sp
  5908. Adversely
  5909. affects the operator's accomplishment of an
  5910. operational or mission essential capability
  5911. specified by baselined requirements so as to
  5912. degrade performance and for which an alternative
  5913. work-around solution is known.
  5914. .li -5
  5915. .ri -5
  5916. .sp
  5917. 4: A software problem that is an operator inconvenience
  5918. or annoyance and which does not affect a required
  5919. operational or mission essential capability
  5920. .sp
  5921. 5: All other errors
  5922. .bp
  5923. .sp 20
  5924. .ce
  5925. This Page Intentionally Blank
  5926.